diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md new file mode 100644 index 000000000..176bd9a28 --- /dev/null +++ b/COLLABORATOR_GUIDE.md @@ -0,0 +1,100 @@ +# jade Collaborator Guide + +**Contents** + +* Issues and Pull Requests +* Accepting Modifications + - Involving the TC +* Landing Pull Requests + - Technical HOWTO + +This document contains information for Collaborators of the jade +project regarding maintaining the code, documentation and issues. + +Collaborators should be familiar with the guidelines for new +contributors in [CONTRIBUTING.md](./CONTRIBUTING.md). + +## Issues and Pull Requests + +Courtesy should always be shown to individuals submitting issues and +pull requests to the jade project. + +Collaborators should feel free to take full responsibility for +managing issues and pull requests they feel qualified to handle, as +long as this is done while being mindful of these guidelines and the +opinions of other Collaborators. + +Collaborators may **close** any issue or pull request they believe is +not relevant for the future of the jade project. Where this is +unclear, the issue should be left open for several days to allow for +additional discussion. Where this does not yield input from jade +Collaborators or additional evidence that the issue has relevance, the +issue may be closed. Remember that issues can always be re-opened if +necessary. + +## Accepting Modifications + +All modifications to the jade code and documentation should be +performed via GitHub pull requests, including modifications by +Collaborators. + +All pull requests must be reviewed and accepted by a Collaborator with +sufficient expertise who is able to take full responsibility for the +change. In the case of pull requests proposed by an existing +Collaborator, an additional Collaborator is required for sign-off. + +In some cases, it may be necessary to summon a qualified Collaborator +to a pull request for review by @-mention. + +If you are unsure about the modification and are not prepared to take +full responsibility for the change, defer to another Collaborator. + +Before landing pull requests, sufficient time should be left for input +from other Collaborators. Leave at least 48 hours during the week and +72 hours over weekends to account for international time differences +and work schedules. Trivial changes (e.g. those which fix minor bugs +or improve performance without affecting API or causing other +wide-reaching impact) may be landed after a shorter delay. + +Where there is no disagreement amongst Collaborators, a pull request +may be landed given appropriate review. Where there is discussion +amongst Collaborators, consensus should be sought if possible. + +All bugfixes require a test case which demonstrates the defect. The +test should *fail* before the change, and *pass* after the change. + +### Building documentation + +For local builds run ```node docs/server.js```. + +To update the live page, create a file with the name ```.release.json```, +[generate a GitHub token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) +and put it into the file so that it be read with JSON.parse: + +``` +"abc123..." +``` + +Then run ```node release.js``` which will build it from the "docs" directory +and commit it to gh-pages automatically. + +### Releasing + +Open an issue with a proposed changelog and semver-compatible version number. + +Once this has been approved by the Collaborators, run ```npm prepublish```, +update ```History.md``` with the new changelog, bump the version number in +```package.json``` as well as ```component.json``` and tag the new release. + +Commit these changes and run ```npm publish```. + +### I just made a mistake + +With git, there's a way to override remote trees by force pushing +(`git push -f`). On master, this should be seen as forbidden (since +you're rewriting history on a repository other people are working +against) but is allowed for simpler slip-ups such as typos in commit +messages. However, you are only allowed to force push to any jade +branch within 10 minutes from your original push. If someone else +pushes to the branch your commit lives in or the 10 minute period +passes, consider the commit final. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..846a5720b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,128 @@ +# Contributing to jade + +Please feel free to open an issue with jade for *any* communication, such as +questions or bugs. + +For bugs, please search the docs first. If the bug persists, please create an +issue and post the entire error message, log and source code, so that it can +be reproduced as accurately as possible. + +### Step 1: Fork + +Fork the project [on GitHub](https://github.com/jadejs/jade) and check out your +copy locally. + +```text +$ git clone git@github.com:username/jade.git +$ cd jade +$ git remote add upstream git://github.com/jadejs/jade.git +``` + +#### Which branch? + +For developing new features and bug fixes, the `master` branch should be pulled +and built upon. + +### Step 2: Branch + +Create a feature branch and start hacking: + +```text +$ git checkout -b my-feature-branch -t origin/master +``` + +### Step 3: Commit + +Make sure git knows your name and email address: + +```text +$ git config --global user.name "J. Random User" +$ git config --global user.email "j.random.user@example.com" +``` + +### Step 4: Rebase + +Use `git rebase` (not `git merge`) to sync your work from time to time. + +```text +$ git fetch upstream +$ git rebase upstream/master +``` + +### Step 5: Test + +Bug fixes and features **should come with tests**. Add your tests in the +test/ directory. Look at other tests to see how they should be +structured (license boilerplate, common includes, etc.). + +```text +$ npm test +``` + +### Step 6: Push + +```text +$ git push origin my-feature-branch +``` + +Go to https://github.com/yourusername/jades and select your feature branch. +Click the 'Pull Request' button and fill out the form. + +Pull requests are usually reviewed within a few days. If there are comments +to address, apply your changes in a separate commit and push that to your +feature branch. Post a comment in the pull request afterwards; GitHub does +not send out notifications when you add commits. + + +## Developer's Certificate of Origin 1.0 + +By making a contribution to this project, I certify that: + +* (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license indicated + in the file; or +* (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source license + and I have the right under that license to submit that work with + modifications, whether created in whole or in part by me, under the + same open source license (unless I am permitted to submit under a + different license), as indicated in the file; or +* (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified it. + + +## Code of Conduct + +This Code of Conduct is adapted from [Rust's wonderful +CoC](http://www.rust-lang.org/conduct.html). + +* We are committed to providing a friendly, safe and welcoming + environment for all, regardless of gender, sexual orientation, + disability, ethnicity, religion, or similar personal characteristic. +* Please avoid using overtly sexual nicknames or other nicknames that + might detract from a friendly, safe and welcoming environment for + all. +* Please be kind and courteous. There's no need to be mean or rude. +* Respect that people have differences of opinion and that every + design or implementation choice carries a trade-off and numerous + costs. There is seldom a right answer. +* Please keep unstructured critique to a minimum. If you have solid + ideas you want to experiment with, make a fork and see how it works. +* We will exclude you from interaction if you insult, demean or harass + anyone. That is not welcome behaviour. We interpret the term + "harassment" as including the definition in the [Citizen Code of + Conduct](http://citizencodeofconduct.org/); if you have any lack of + clarity about what might be included in that concept, please read + their definition. In particular, we don't tolerate behavior that + excludes people in socially marginalized groups. +* Private harassment is also unacceptable. No matter who you are, if + you feel you have been or are being harassed or made uncomfortable + by a community member, please open an issue immediately with a capture + (log, photo, email) of the harassment if possible. Whether you're a + regular contributor or a newcomer, we care about making this community + a safe place for you and we've got your back. +* Likewise any spamming, trolling, flaming, baiting or other + attention-stealing behaviour is not welcome. +* Avoid the use of personal pronouns in code comments or + documentation. There is no need to address persons when explaining + code (e.g. "When the developer")