Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update contributing instructions #767

Merged
merged 1 commit into from
Feb 7, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 20 additions & 18 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,14 @@ Interested in contributing to Vale? Great—we welcome contributions of any

- [Contributing to Vale](#contributing-to-vale)
- [Table of Contents](#table-of-contents)
- [<a name="intro"></a> Introduction](#-introduction)
- [<a name="testing"></a> Testing](#-testing)
- [<a name="devenv"></a> Setting up a Development Environment](#-setting-up-a-development-environment)
- [<a name="code-guidelines"></a> Code Contribution Guidelines](#-code-contribution-guidelines)
- [<a name="commit-guidelines"></a> Git Commit Message Guidelines](#-git-commit-message-guidelines)
- [<a name="terms"></a> Terminology](#-terminology)
- [Introduction](#introduction)
- [Testing](#testing)
- [Setting up a Development Environment](#setting-up-a-development-environment)
- [Code Contribution Guidelines](#code-contribution-guidelines)
- [Git Commit Message Guidelines](#git-commit-message-guidelines)
- [Terminology](#terminology)

## <a name="intro"></a> Introduction
## Introduction

Vale is a natural language linter that supports plain text, markup (Markdown, reStructuredText, AsciiDoc, and HTML), and source code comments. However, unlike many similar projects, Vale's primary focus isn't on providing a collection of rules everyone must follow&mdash;instead, Vale aims to be flexible enough to support many different styles (see [Styles](https://errata-ai.github.io/vale/styles/) for more information).

Expand All @@ -27,7 +27,7 @@ More specifically, Vale is written in Go and split into packages that are tasked

If you're looking to improve Vale's documentation, check out the [`docs/`](https://github.com/errata-ai/vale/tree/master/docs) directory.

## <a name="testing"></a> Testing
## Testing

Vale is tested using both integration and unit tests.

Expand All @@ -43,20 +43,22 @@ LintMD-2 1.54s ± 1% 1.54s ± 1% ~ (p=0.604 n=10+10)

To run the tests, you'll want to invoke either `make bench` or `make ci` (see [Setting up a Development Environment]() for more information).

## <a name="devenv"></a> Setting up a Development Environment
## Setting up a Development Environment

You'll need to have [Ruby](https://www.ruby-lang.org/en/downloads/) (v2.3+) and [Go](https://golang.org/) (v1.7+) installed. Next, you'll need to install and configure [`aruba`](https://github.com/cucumber/aruba) (assuming you're inside the `vale` directory):
Prerequisites:

* [Ruby](https://www.ruby-lang.org/en/downloads/) (v2.3+)
* [Go](https://golang.org/) (v1.7+) installed.
* [Asciidoctor](http://asciidoctor.org/) available on your `$PATH`.
* [rst2html](http://docutils.sourceforge.net/docs/user/tools.html#rst2html-py) available on your `$PATH`. The latter is installed with both [Sphinx](http://www.sphinx-doc.org/en/stable/) and [docutils](https://pypi.python.org/pypi/docutils).

```bash
$ gem install bundler # if necessary
$ aruba init --test-framework cucumber
$ gem install bundler:2.2.31 # if necessary
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added the specific version here, otherwise the install complained about me using a more recent recent version of bundler than the one used to generate the lockfile. I could have regenerated the lockfile but without 100% passing tests that seemed unsafe.

$ make setup
$ make ci
$ make test
```

To get all tests passing, you'll also need [Asciidoctor](http://asciidoctor.org/) and [rst2html](http://docutils.sourceforge.net/docs/user/tools.html#rst2html-py) available on your `$PATH`. The latter is installed with both [Sphinx](http://www.sphinx-doc.org/en/stable/) and [docutils](https://pypi.python.org/pypi/docutils).

## <a name="code-guidelines"></a> Code Contribution Guidelines
## Code Contribution Guidelines

To make the contribution process as seamless as possible, we ask for the following:

Expand All @@ -66,7 +68,7 @@ To make the contribution process as seamless as possible, we ask for the followi
* Squash your commits into a single commit. `git rebase -i`. It’s okay to force update your pull request with `git push -f`.
* Follow the **Git Commit Message Guidelines** below.

## <a name="commit-guidelines"></a> Git Commit Message Guidelines
## Git Commit Message Guidelines

Vale follows a modified version of the [AngularJS Commit Guidelines](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#-git-commit-guidelines). A commit message should take the following form:

Expand Down Expand Up @@ -99,7 +101,7 @@ Also demotes `Annotations` and `PassiveVoice` to "suggestions."
Related to #30.
```

## <a name="terms"></a> Terminology
## Terminology

| Term | Definition |
|:-----:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
Expand Down