Skip to content

Latest commit

 

History

History
72 lines (55 loc) · 3.55 KB

CONTRIBUTING.md

File metadata and controls

72 lines (55 loc) · 3.55 KB
Raw

Pull Requests

If you're thinking about making some changes, maybe fixing a bug, or adding a snazzy new feature, first, thank you. Contributions are very welcome. Things need to be manageable for the maintainers, however. So below you'll find The fastest way to get your pull request merged in. Some things, particularly how you set up your branches and work with git, are just suggestions, but pretty good ones.

  1. Create a remote to track the base jsdoc3/jsdoc repository This is just a convenience to make it easier to update your <tracking branch> (more on that shortly). You would execute something like:

     git remote add base git://github.com/jsdoc3/jsdoc.git

    Here 'base' is the name of the remote. Feel free to use whatever you want.

  2. Set up a tracking branch for the base repository We're gonna call this your <tracking branch>. You will only ever update this branch by pulling from the 'base' remote. (as opposed to 'origin')

     git branch --track pullpost base/master
 git checkout pullpost

    Here 'pullpost' is the name of the branch. Fell free to use whatever you want.

  3. Create your change branch Once you are in <tracking branch>, make sure it's up to date, then create a branch for your changes off of that one.

     git branch fix-for-issue-395
 git checkout fix-for-issue-395

    Here 'fix-for-issue-395' is the name of the branch. Feel free to use whatever you want. We'll call this the <change branch>. This is the branch that you will eventually issue your pull request from.

    The purpose of these first three steps is to make sure that your merge request has a nice clean diff that only involves the changes related to your fix/feature.

  4. Make your changes On your <change branch> make any changes relevant to your fix/feature. Don't group fixes for multiple unrelated issues or multiple unrelated features together. Create a separate branch for each unrelated changeset. For instance, if you're fixing a bug in the parser and adding some new UI to the default template, those should be separate branches and merge requests.

    Also, if you want to change package.json, note that you must make your changes in Jake/templates/package.json.tmpl, then run jake.

  5. Add tests Add tests for your change. If you are submitting a bugfix, include a test that verifies the existence of the bug along with your fix. If you are submitting a new feature, include tests that verify proper feature function, if applicable. See the readme in the 'test' directory for more information

  6. Commit and publish Commit your changes and publish your branch (or push it if it's already published)

  7. Issue your pull request On github.com, switch to your <change branch> and click the 'Pull Request' button. Enter some meaningful information about the pull request. If it's a bugfix, that doesn't already have an issue associated with it, provide some info on what situations that bug occurs in and a sense of it's severity. If it does already have an issue, make sure the include the hash and issue number (e.g. '#100') so github links it.

    If it's a feature, provide some context about the motivations behind the feature, why it's important/useful/cool/necessary and what it does/how it works. Don't worry about being too verbose. Folks will be much more amenable to reading through your code if they know what its supposed to be about.