diff --git a/HOW_TO_CONTRIBUTE.md b/HOW_TO_CONTRIBUTE.md new file mode 100644 index 00000000..992136ce --- /dev/null +++ b/HOW_TO_CONTRIBUTE.md @@ -0,0 +1,69 @@ +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 `````` + (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 ``````. 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 ``````, 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 ``````. 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 `````` 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. + +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 `````` 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. diff --git a/README.md b/README.md index 6b2ea794..00d0668b 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,8 @@ Notice This is *beta software*! It is available for testing purposes and may not be suitable for production use yet. +### Pull Requesters: Please read HOW_TO_CONTRIBUTE.md + Installation ------------ diff --git a/package.json b/package.json index ed6f2d26..575f4099 100644 --- a/package.json +++ b/package.json @@ -1,36 +1,44 @@ { - "name": "JSDoc", - "version": "3.0.0alpha", - "revision": "1323947228470", - "description": "An automatic documentation generator for javascript.", - "keywords": [ "documentation", "javascript" ], - "licenses": [ - { - "type": "Apache 2.0", - "url": "http://www.apache.org/licenses/LICENSE-2.0" - } - ], - "repositories": [ - { - "type": "git", - "url": "git://github.com/micmath/jsdoc.git" - } - ], - "bugs": "https://github.com/micmath/jsdoc/issues", - "contributors" : [ + "name": "JSDoc", + "version": "3.0.0alpha", + "revision": "1323947228470", + "description": "An automatic documentation generator for javascript.", + "keywords": ["documentation", "javascript"], + "licenses": [ { - "name": "Michael Mathews", - "email": "micmath@gmail.com" - }, - { - "name": "Rafa\u0105 Wrzeszcz", - "email": "rafal.wrzeszcz@wrzasq.pl" - } + "type": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0" + } ], - "maintainers": [ - { - "name": "Michael Mathews", - "email": "micmath@gmail.com" - } + "repositories": [ + { + "type": "git", + "url": "git://github.com/micmath/jsdoc.git" + } + ], + "bugs": "https://github.com/micmath/jsdoc/issues", + "contributors": [ + { + "name": "Michael Mathews", + "email": "micmath@gmail.com" + }, + { + "name": "Rafa\u0105 Wrzeszcz", + "email": "rafal.wrzeszcz@wrzasq.pl" + }, + { + "name": "Jannon Frank", + "email": "jannon@jannon.net" + } + ], + "maintainers": [ + { + "name": "Michael Mathews", + "email": "micmath@gmail.com" + }, + { + "name": "Jannon Frank", + "email": "jannon@jannon.net" + } ] } diff --git a/plugins/README.md b/plugins/README.md index c5a8bd21..2bcd774c 100644 --- a/plugins/README.md +++ b/plugins/README.md @@ -72,7 +72,7 @@ source code being documented, like methods provided by a third-party superclass: "@memberof ui.mywidget", "@function", "*/", ""]; - e.comment += extraDoc.join("\n"); + e.source += extraDoc.join("\n"); } } diff --git a/test/README.md b/test/README.md index dd5406b3..af63c566 100644 --- a/test/README.md +++ b/test/README.md @@ -1,3 +1,7 @@ From the project root, run the following command in the terminal: java -jar lib/js.jar -modules rhino_modules -modules node_modules jsdoc.js -T + +TODO: + +More info for contributors about how tests work and about plugin/template tests \ No newline at end of file