archive-gh-me/jsdoc
1
0
Fork 0
mirror of https://github.com/jsdoc/jsdoc.git synced 2025-12-08 19:46:11 +00:00
Code Issues Projects Releases Wiki Activity

Merge pull request #108 from jannon/ProjectAdmin

Browse Source 
Readme additions and pull request instructions
This commit is contained in:
Jannon Frank 2012-04-21 03:21:29 -07:00
commit 562816c75d
5 changed files with 115 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
HOW_TO_CONTRIBUTE.md Normal file
View File

@ -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 ```<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.
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.

2
README.md
View File

@ -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
------------

70
package.json
View File

@ -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"
}
]
}

2
plugins/README.md
View File

@ -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");
}
}

4
test/README.md
View File

@ -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