Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Docs: Add Contributing Documentation (fixes #61)
  • Loading branch information
Casey Visco committed Jul 16, 2016
1 parent 326c2b1 commit 22898dc
Show file tree
Hide file tree
Showing 5 changed files with 237 additions and 2 deletions.
12 changes: 12 additions & 0 deletions CONTRIBUTING.md
@@ -0,0 +1,12 @@
# Contributing

Please be sure to read the following contribution guidelines before making or
requesting a change.

### Filing an issue?

Please read the [Issue Guidelines](docs/contributing/issues.md).

### Contributing code?

Please read the [Pull Request Guidelines](docs/contributing/pull-requests.md).
4 changes: 2 additions & 2 deletions README.md
Expand Up @@ -93,8 +93,8 @@ Take a look at what's in progress for the next [milestone](https://github.com/cv

Contributions are encouraged. There are a few ways you can help:

* **Filing issues** - if you find a bug or would like to request a new rule or enhancement, [file an issue](https://github.com/cvisco/eslint-plugin-requirejs/issues)
* **Submitting pull requests** - pick one of the open [issues](https://github.com/cvisco/eslint-plugin-requirejs/issues) to work on and submit a [pull request](https://github.com/cvisco/eslint-plugin-requirejs/pulls)
* **Filing issues** - if you find a bug or would like to request a new rule or enhancement, [file an issue](docs/contributing/issues.md)
* **Submitting pull requests** - pick one of the open [issues](https://github.com/cvisco/eslint-plugin-requirejs/issues) to work on and submit a [pull request](docs/contributing/pull-requests.md)

## License

Expand Down
67 changes: 67 additions & 0 deletions docs/contributing/dev-environment.md
@@ -0,0 +1,67 @@
# Development Environment

This plugin has a lightweight development environment that's very similar to ESLint's own.

## Setup

This is a step-by-step guide to setting up a local development environment that will let you contribute to the project.

### Step 1: Install Node.js and npm

Download and install the latest stable version from http://nodejs.org/. Alternatively, you may use a version manager such as [Node Version Manager](https://github.com/creationix/nvm) or [n](https://github.com/tj/n). Most installers also include [npm](http://npmjs.org/).

### Step 2: Fork and checkout this repository

Go to the [eslint-plugin-requirejs repo](https://github.com/cvisco/eslint-plugin-requirejs) and click the “Fork” button. Follow the GitHub documentation for forking and cloning.

Once you’ve cloned the repository, run `npm install` to get all the necessary dependencies:

$ cd eslint-plugin-requirejs
$ npm install

### Step 3: Add the upstream source

The upstream source is the main repository that active development happens on. Setting the upstream source will allow you to pull in the latest code whenever you want.

To add the upstream source for eslint-plugin-requirejs, run the following in your repository:

$ git remote add upstream git@github.com:cvisco/eslint-plugin-requirejs.git

### Step 4: Run the tests

Running the tests is the best way to ensure you have correctly set up your development environment. Make sure you’re in the the eslint-plugin-requirejs directory and run:

$ npm test

The testing should only take a few seconds to complete. If any tests fail, that likely means one or more parts of the environment setup didn’t complete correctly. The upstream tests always pass.

## Development Workflow

Whenever you make changes to the source files, you’ll need to run `npm test` to rerun the tests. The workflow is:

1. Make changes
2. Run `npm test` to run tests on the command line

You’ll have to do this each time you make a change. The tests are run automatically whenever a pull request is received, so make sure to verify your changes work before submitting them.

## Build Scripts

This project has several build scripts that help with various parts of development.

### npm test

The primary script to use is `npm test`, which does several things:

1. Lints all JavaScript (including tests and makefile)
2. Runs all tests
3. Checks code coverage targets

Be sure to run this after making changes and before sending a pull request with your changes.

### npm run unit

If you need to skip the lint check for any reason (useful during debugging), you can use this script to run the tests by themselves.

### npm run lint

You can use this script to lint the code without running the tests.
33 changes: 33 additions & 0 deletions docs/contributing/issues.md
@@ -0,0 +1,33 @@
# Filing Issues

Before filing an issue, please be sure to read the guidelines for what you're
reporting:

## Reporting Bugs

If you think you’ve found a bug in the eslint-plugin-requirejs code, please [file an issue](https://github.com/cvisco/eslint-plugin-requirejs/issues) on GitHub. Be sure to include the following information:

* The version of ESLint you are using
* The version of the plugin you are using
* The actual source code that is causing the issue
* In the case of an exception, the _complete_ output from ESLint

You can never have too much detail in your bug report, so please include as much detail as possible to help us properly address your issue.

## Requesting a New Rule

All rules in this plugin focus on specific [RequireJS](http://requirejs.org) features, patterns or potential issues. Any proposed new rule should do the same. Rules must be as atomic as possible, and not overlap with other rules. If you would like to propose a new rule, please [file an issue](https://github.com/cvisco/eslint-plugin-requirejs/issues) on GitHub. Be sure to include the following information:

* When the rule will warn. Include a description as well as sample code.
* Whether the rule prevents an error or is stylistic.
* If you are interested or willing to create the rule yourself

## Changes to Existing Rules

In the event that a rule is found to be incomplete or inflexible, it may need an enhancement. If you would like to propose an enhancement to an existing rule, please [file an issue](https://github.com/cvisco/eslint-plugin-requirejs/issues) on GitHub. Be sure to include the following information:

* The version of ESLint you are using
* The version of the plugin you are using
* The rule you want to change
* The source code you want to be flagged as incorrect
* What happens when the rule is applied to the code without your change
123 changes: 123 additions & 0 deletions docs/contributing/pull-requests.md
@@ -0,0 +1,123 @@
# Pull Requests

If you want to contribute to the eslint-plugin-requirejs repo, please use a GitHub pull request. This is the fastest way for us to evaluate your code and to merge it into the code base.

## Getting Started

If you’d like to work on a pull request, follow these steps:

1. Set up a [development environment](dev-environment.md).
2. Ensure there’s an issue that describes what you’re doing. You can [create a new issue](issues.md) or work on an [existing issue](https://github.com/cvisco/eslint-plugin-requirejs/issues).
3. Documentation-only changes do not require an issue and may be submitted directly from the GitHub website.

## Working with the Code

The process of submitting a pull request for this plugin is almost identical to that of ESLint and follows the same pattern each time:

### Step 1: Create a new branch

Create a new branch in your eslint-plugin-requirejs fork. Give the branch a descriptive name that describes what it is you’re fixing, such as:

$ git checkout -b issue-12

You should do all of your development for the issue in this branch.

**Note:** Do not combine fixes for multiple issues into one branch. Use a separate branch for each issue you’re working on.

### Step 2: Make your changes

Make the changes to the code, tests and relevant documentation, following the existing code conventions as you go. Once you have finished, commit the changes to your branch:

$ git add -A
$ git commit

Our commit message format is as follows:

Tag: Short description (fixes #12)

Longer description here if necessary

The first line of the commit message (the summary) must have a specific format.

The `Tag` is one of the following:

* `Fix` - for a bug fix.
* `Update` - for a backwards-compatible enhancement or change to an existing rule.
* `New` - implemented a new feature or rule.
* `Breaking` - for a backwards-_incompatible_ enhancement or feature.
* `Docs` - changes to documentation only.
* `Build` - changes to build process only.
* `Upgrade` - for a dependency upgrade.
* `Chore` - for refactoring, adding tests, etc. (anything that isn’t user-facing).

The message summary should be a one-sentence description of the change, and it must be 72 characters in length or shorter. The issue number should be mentioned at the end.

The commit message format is important because these messages are used to automatically generate a changelog for each release. The tag and issue number help to create more consistent and useful changelogs.

### Step 3: Rebase onto upstream

Before you send the pull request, be sure to rebase onto the upstream source. This ensures your code is running on the latest available code.

$ git fetch upstream
$ git rebase upstream/master

### Step 4: Run the tests

After rebasing, be sure to run all of the tests once again to make sure nothing broke:

$ npm test

If there are any failing tests, update your code until all tests pass.

### Step 5: Push your changes

Next, push your changes to your clone:

$ git push origin issue-12

If you are unable to push because some references are old, do a forced push instead:

$ git push -f origin issue-12

### Step 6: Submit the pull request

Now you’re ready to send the pull request. Go to your eslint-plugin-requirejs fork and then follow the [GitHub documentation](https://help.github.com/articles/creating-a-pull-request/) on how to send a pull request.

## Code Review

Once your pull request is sent, it may take some time to fully review. In the mean time, here are a few points to keep in mind:

* Monitor the status of the Travis CI build for your pull request. If it fails, please investigate why. We will not merge pull requests with broken tests or reduced code coverage.
* Respond to comments left on the pull request from reviewers. Remember, we want to help you land your code, so please be receptive to feedback.
* We may ask you to make changes, rebase, or squash your commits.

### Updating the Commit Message

If your commit message is in the incorrect format, you’ll be asked to update it. You can do so via:

$ git commit --amend

This will open up your editor so you can make changes. After that, you’ll need to do a forced push to your branch:

$ git push -f origin issue-12

### Updating the Code

If you are asked to make code changes, there’s no need to close the pull request and create a new one. Just go back to the branch on your fork and make your changes. Then, when you’re ready, you can add your changes into the branch:

$ git add -A
$ git commit --amend
$ git push -f origin issue-12

This adds all your new changes, then amends the previous commit with them.

### Rebasing

If your code is out-of-date, you may be asked to rebase. That means we want you to apply your changes on top of the latest upstream code. Make sure you have set up a development environment and then you can rebase using these commands:

$ git fetch upstream
$ git rebase upstream/master

You might find that there are merge conflicts when you attempt to rebase. Please resolve the conflicts and then do a forced push to your branch:

$ git push -f origin issue-12

0 comments on commit 22898dc

Please sign in to comment.