From 22898dc580f59154fd8fa4ae2956b0ff0111a4a7 Mon Sep 17 00:00:00 2001 From: Casey Visco Date: Sat, 16 Jul 2016 01:03:16 -0400 Subject: [PATCH] Docs: Add Contributing Documentation (fixes #61) --- CONTRIBUTING.md | 12 +++ README.md | 4 +- docs/contributing/dev-environment.md | 67 +++++++++++++++ docs/contributing/issues.md | 33 +++++++ docs/contributing/pull-requests.md | 123 +++++++++++++++++++++++++++ 5 files changed, 237 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 docs/contributing/dev-environment.md create mode 100644 docs/contributing/issues.md create mode 100644 docs/contributing/pull-requests.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c4308ae --- /dev/null +++ b/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). diff --git a/README.md b/README.md index e635243..e7acac0 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/contributing/dev-environment.md b/docs/contributing/dev-environment.md new file mode 100644 index 0000000..53352ab --- /dev/null +++ b/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. diff --git a/docs/contributing/issues.md b/docs/contributing/issues.md new file mode 100644 index 0000000..3255e4d --- /dev/null +++ b/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 diff --git a/docs/contributing/pull-requests.md b/docs/contributing/pull-requests.md new file mode 100644 index 0000000..2ce187f --- /dev/null +++ b/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