73 lines
3.5 KiB
Markdown
73 lines
3.5 KiB
Markdown
|
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.
|