From f1d77201353a56949c2c7fe3e06984cfb35a7f2c Mon Sep 17 00:00:00 2001 From: Andreas Lubbe Date: Sat, 6 Jun 2015 15:31:34 +0200 Subject: [PATCH 1/2] add CONTRIBUTING.md and COLLABORATOR_GUIDE.md --- COLLABORATOR_GUIDE.md | 96 ++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 125 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 221 insertions(+) create mode 100644 COLLABORATOR_GUIDE.md create mode 100644 CONTRIBUTING.md diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md new file mode 100644 index 000000000..c0b987ed8 --- /dev/null +++ b/COLLABORATOR_GUIDE.md @@ -0,0 +1,96 @@ +# 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 + +Create a file with the name ```.release.json``` and put your GitHub token +into it so that it be read with JSON.parse: + +``` +"abc123..." +``` + +Run ```node release.js``` which will build it from the "docs" directory and then 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 and bump the version number in +```package.json``` and ```component.json```. + +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`). This should generally 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..8a2e0b564 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,125 @@ +# Contributing to jade + +### 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 +``` + +Make sure that all tests pass. Please, do not submit patches that fail. + + +### 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 contact one of the channel ops or any + of the TC members 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") From 3ebf1ed9bf8ffa05d9385b3394dd1d4fb2f89a96 Mon Sep 17 00:00:00 2001 From: Andreas Lubbe Date: Thu, 18 Jun 2015 12:10:40 +0200 Subject: [PATCH 2/2] update COLLABORATOR_GUIDE and CONTRIBUTING --- COLLABORATOR_GUIDE.md | 16 ++++++++++------ CONTRIBUTING.md | 19 +++++++++++-------- 2 files changed, 21 insertions(+), 14 deletions(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index c0b987ed8..176bd9a28 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -65,29 +65,33 @@ test should *fail* before the change, and *pass* after the change. ### Building documentation -Create a file with the name ```.release.json``` and put your GitHub token -into it so that it be read with JSON.parse: +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..." ``` -Run ```node release.js``` which will build it from the "docs" directory and then commit it to gh-pages automatically. +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 and bump the version number in -```package.json``` and ```component.json```. +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`). This should generally be seen as forbidden (since +(`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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8a2e0b564..846a5720b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,12 @@ # 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 @@ -52,9 +59,6 @@ structured (license boilerplate, common includes, etc.). $ npm test ``` -Make sure that all tests pass. Please, do not submit patches that fail. - - ### Step 6: Push ```text @@ -113,11 +117,10 @@ CoC](http://www.rust-lang.org/conduct.html). 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 contact one of the channel ops or any - of the TC members 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. + 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