You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by wo...@apache.org on 2017/05/20 20:16:37 UTC
[couchdb] branch master updated: Add/update contribution guidelines,
issue/PR templates for GH Issues
This is an automated email from the ASF dual-hosted git repository.
wohali pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/couchdb.git
The following commit(s) were added to refs/heads/master by this push:
new 060fd63 Add/update contribution guidelines, issue/PR templates for GH Issues
060fd63 is described below
commit 060fd6326be832b827f205e95a35bca1350ff54d
Author: Joan Touzet <jo...@atypical.net>
AuthorDate: Wed May 17 13:57:50 2017 -0400
Add/update contribution guidelines, issue/PR templates for GH Issues
---
.github/ISSUE_TEMPLATE.md | 32 +++++
.github/PULL_REQUEST_TEMPLATE.md | 26 ++--
CONTRIBUTING.md | 290 +++++++++++++++++++++++++++++++++++++++
README.rst | 15 +-
4 files changed, 348 insertions(+), 15 deletions(-)
diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
new file mode 100644
index 0000000..be4f816
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE.md
@@ -0,0 +1,32 @@
+<!--- Provide a general summary of the issue in the Title above -->
+
+## Expected Behavior
+<!--- If you're describing a bug, tell us what should happen -->
+<!--- If you're suggesting a change/improvement, tell us how it should work -->
+
+## Current Behavior
+<!--- If describing a bug, tell us what happens instead of the expected behavior -->
+<!--- If suggesting a change/improvement, explain the difference from current behavior -->
+
+## Possible Solution
+<!--- Not obligatory, but suggest a fix/reason for the bug, -->
+<!--- or ideas how to implement the addition or change -->
+
+## Steps to Reproduce (for bugs)
+<!--- Provide a link to a live example, or an unambiguous set of steps to -->
+<!--- reproduce this bug. Include code to reproduce, if relevant -->
+1.
+2.
+3.
+4.
+
+## Context
+<!--- How has this issue affected you? What are you trying to accomplish? -->
+<!--- Providing context helps us come up with a solution that is most useful in the real world -->
+
+## Your Environment
+<!--- Include as many relevant details about the environment you experienced the bug in -->
+* Version used:
+* Browser Name and version:
+* Operating System and version (desktop or mobile):
+* Link to your project:
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 71ea992..f364446 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,14 +1,15 @@
<!-- Thank you for your contribution!
- Please file this form by replacing markdown commentary
- tags with the text. If section needs in no action - remove it.
+ Please file this form by replacing the Markdown comments
+ with your text. If a section needs no action - remove it.
Also remember, that CouchDB uses the Review-Then-Commit (RTC) model
- of code collaboration. Positive feedback provides by +1 from committers
- while negative by -1. The -1 also means veto and need to be addressed
- to find the consensus. Once there are no objections, PR could be merged.
+ of code collaboration. Positive feedback is represented +1 from committers
+ and negative is a -1. The -1 also means veto, and needs to be addressed
+ to proceed. Once there are no objections, the PR can be merged by a
+ CouchDB committer.
- See: http://couchdb.apache.org/bylaws.html#decisions for more info -->
+ See: http://couchdb.apache.org/bylaws.html#decisions for more info. -->
## Overview
@@ -21,16 +22,17 @@
Does it provides any behaviour that the end users
could notice? -->
-## JIRA issue number
+## GitHub issue number
-<!-- If this is a significant change, please file a JIRA issue at:
- https://issues.apache.org/jira/browse/COUCHDB
- and include the number here and in commit message(s) -->
+<!-- If this is a significant change, please file a separate issue at:
+ https://github.com/apache/couchdb/issues
+ and include the number here and in commit message(s) using
+ syntax like "Fixes #472" or "Fixes apache/couchdb#472". -->
## Related Pull Requests
-<!-- If your changes affects on multiple components in different
- repositories please list here links to those pull requests. -->
+<!-- If your changes affects multiple components in different
+ repositories please put links to those pull requests here. -->
## Checklist
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..884d3af
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,290 @@
+# Contributing to CouchDB
+
+Please take a moment to review this document in order to make the contribution
+process easy and effective for everyone involved.
+
+Following these guidelines helps to communicate that you respect the time of
+the developers managing and developing this open source project. In return,
+they should reciprocate that respect in addressing your issue, assessing
+changes, and helping you finalize your pull requests.
+
+Contributions to CouchDB are governed by our [Code of Conduct][6] and a set of
+[Project Bylaws][7]. Come join us!
+
+
+## Using the issue tracker
+
+First things first: **Do NOT report security vulnerabilities in public issues!**
+Please disclose responsibly by letting [the Apache CouchDB Security team](mailto:security@couchdb.apache.org?subject=Security)
+know upfront. We will assess the issue as soon as possible on a best-effort
+basis and will give you an estimate for when we have a fix and release available
+for an eventual public disclosure.
+
+The GitHub issue tracker is the preferred channel for [bug reports](#bugs),
+[features requests](#features) and [submitting pull requests](#pull-requests),
+but please respect the following restrictions:
+
+* Please **do not** use the issue tracker for personal support requests. Use
+ [CouchDB Chat][8] instead. Alternately, help us to help more people by
+ using our publicly archived [user][1] or [developer][5] mailing lists.
+
+* Please **do not** derail or troll issues. Keep the discussion on topic and
+ respect the opinions of others.
+
+
+## Bug reports
+
+A bug is a _demonstrable problem_ that is caused by the code in our
+repositories. Good bug reports are extremely helpful - thank you!
+
+Guidelines for bug reports:
+
+1. **Use the GitHub issue search** — check if the issue has already been
+ reported.
+
+2. **Check if the issue has been fixed** — try to reproduce it using the
+ latest `master` or `next` branch in the repository.
+
+3. **Isolate the problem** — ideally create a reduced test case.
+
+A good bug report shouldn't leave others needing to chase you up for more
+information. Please try to be as detailed as possible in your report. What is
+your environment? What steps will reproduce the issue? What OS experiences the
+problem? What would you expect to be the outcome? All these details will help
+people to fix any potential bugs. Our issue template will help you include all
+of the relevant detail.
+
+Example:
+
+> Short and descriptive example bug report title
+>
+> A summary of the issue and the browser/OS environment in which it occurs. If
+> suitable, include the steps required to reproduce the bug.
+>
+> 1. This is the first step
+> 2. This is the second step
+> 3. Further steps, etc.
+>
+> `<url>` - a link to the reduced test case
+>
+> Any other information you want to share that is relevant to the issue being
+> reported. This might include the lines of code that you have identified as
+> causing the bug, and potential solutions (and your opinions on their
+> merits).
+
+
+## Feature requests
+
+Feature requests are welcome. But take a moment to find out whether your idea
+fits with the scope and aims of the project. It's up to *you* to make a strong
+case to convince the project's developers of the merits of this feature. Please
+provide as much detail and context as possible.
+
+
+## Pull requests
+
+Good pull requests - patches, improvements, new features - are a fantastic
+help. They should remain focused in scope and avoid containing unrelated
+commits.
+
+**Please ask first** before embarking on any significant pull request (e.g.
+implementing features, refactoring code), otherwise you risk spending a lot of
+time working on something that the project's developers might not want to merge
+into the project. You can talk with the community on our
+[developer mailing list][5]. We're always open to suggestions and will get
+back to you as soon as we can!
+
+
+### For new Contributors
+
+If you never created a pull request before, welcome :tada: :smile: [Here is a great tutorial](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github)
+on how to send one :)
+
+1. [Fork](http://help.github.com/fork-a-repo/) the project, clone your fork,
+ and configure the remotes:
+
+ ```bash
+ # Clone your fork of the repo into the current directory
+ git clone https://github.com/<your-username>/<repo-name>
+ # Navigate to the newly cloned directory
+ cd <repo-name>
+ # Assign the original repo to a remote called "upstream"
+ git remote add upstream https://github.com/apache/<repo-name>
+ ```
+
+2. If you cloned a while ago, get the latest changes from upstream:
+
+ ```bash
+ git checkout master
+ git pull upstream master
+ ```
+
+3. Create a new topic branch (off the main project development branch) to
+ contain your feature, change, or fix:
+
+ ```bash
+ git checkout -b <topic-branch-name>
+ ```
+
+4. Make sure to update, or add to the tests when appropriate. Patches and
+ features will not be accepted without tests. Run `make check` to check that
+ all tests pass after you've made changes. Look for a `Testing` section in
+ the project’s README for more information.
+
+5. If you added or changed a feature, make sure to document it accordingly in
+ the [CouchDB documentation](https://github.com/apache/couchdb-documentation)
+ repository.
+
+6. Push your topic branch up to your fork:
+
+ ```bash
+ git push origin <topic-branch-name>
+ ```
+
+8. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/)
+ with a clear title and description.
+
+
+### For Apache CouchDB Committers
+
+1. Be sure to set up [GitHub two-factor authentication](https://help.github.com/articles/about-two-factor-authentication/),
+ then [link your Apache account to your GitHub account](https://gitbox.apache.org/setup/).
+ You will need to wait about 30 minutes after completing this process
+ for it to complete. Follow the instructions in the organisational
+ invite email you receive. Alternately, you can use the Apache mirror
+ of the repository at `https://gitbox.apache.org/asf/repos/<name>.git`
+ if you do not agree to the GitHub Terms of Service.
+
+2. Clone the repo and create a branch.
+
+ ```bash
+ git clone https://github.com/couchdb/<repo-name>
+ # or git clone https://gitbox.apache.org/asf/repos/<name>.git
+ cd <repo-name>
+ git checkout -b <topic-branch-name>
+ ```
+
+3. Make sure to update, or add to the tests when appropriate. Patches and
+ features will not be accepted without tests. Run `make check` to check that
+ all tests pass after you've made changes. Look for a `Testing` section in
+ the project’s README for more information.
+
+4. If you added or changed a feature, make sure to document it accordingly in
+ the [CouchDB documentation](https://github.com/apache/couchdb-documentation)
+ repository.
+
+5. Push your topic branch up to our repo
+
+ ```bash
+ git push origin <topic-branch-name>
+ ```
+
+6. Open a Pull Request using your branch with a clear title and description.
+ Please also add any appropriate labels to the pull request for clarity.
+
+Optionally, you can help us with these things. But don’t worry if they are too
+complicated, we can help you out and teach you as we go :)
+
+1. Update your branch to the latest changes in the upstream master branch. You
+ can do that locally with
+
+ ```bash
+ git pull --rebase upstream master
+ ```
+
+ Afterwards force push your changes to your remote feature branch.
+
+2. Once a pull request is good to go, you can tidy up your commit messages using
+ Git's [interactive rebase](https://help.github.com/articles/interactive-rebase).
+
+**IMPORTANT**: By submitting a patch, you agree to license your work under the
+Apache License, per your signed Apache CLA.
+
+
+## Triagers
+
+Apache CouchDB committers who have completed the GitHub account linking
+process may triage issues. This helps to speed up releases and minimises both
+user and developer pain in working through our backlog.
+
+Briefly, to triage an issue, review the report, validate that it is an actual
+issue (reproducing if possible), and add one or more labels. We have a
+[summary of our label taxonomy](https://github.com/apache/couchdb/issues/499)
+for your reference.
+
+If you are not an official committer, please reach out to our [mailing list][5]
+or [chat][8] to learn how you can assist with triaging indirectly.
+
+
+## Maintainers
+
+If you have commit access, please follow this process for merging patches and cutting new releases.
+
+### Reviewing changes
+
+1. Check that a change is within the scope and philosophy of the component.
+2. Check that a change has any necessary tests.
+3. Check that a change has any necessary documentation.
+4. If there is anything you don’t like, leave a comment below the respective
+ lines and submit a "Request changes" review. Repeat until everything has
+ been addressed.
+5. If you are not sure about something, mention specific people for help in a
+ comment.
+6. If there is only a tiny change left before you can merge it and you think
+ it’s best to fix it yourself, you can directly commit to the author’s fork.
+ Leave a comment about it so the author and others will know.
+7. Once everything looks good, add an "Approve" review. Don’t forget to say
+ something nice 👏🐶💖✨
+8. If the commit messages follow [our conventions](@commit-message-conventions)
+
+ 1. If the pull request fixes one or more open issues, please include the
+ text "Fixes #472" or "Fixes apache/couchdb#472".
+ 2. Use the "Rebase and merge" button to merge the pull request.
+ 3. Done! You are awesome! Thanks so much for your help 🤗
+
+9. If the commit messages _do not_ follow our conventions
+
+ 1. Use the "squash and merge" button to clean up the commits and merge at
+ the same time: ✨🎩
+ 2. If the pull request fixes one or more open issues, please include the
+ text "Fixes #472" or "Fixes apache/couchdb#472".
+
+Sometimes there might be a good reason to merge changes locally. The process
+looks like this:
+
+### Reviewing and merging changes locally
+
+```
+git checkout master # or the main branch configured on github
+git pull # get latest changes
+git checkout feature-branch # replace name with your branch
+git rebase master
+git checkout master
+git merge feature-branch # replace name with your branch
+git push
+```
+
+When merging PRs from forked repositories, we recommend you install the
+[hub](https://github.com/github/hub) command line tools.
+
+This allows you to do:
+
+```
+hub checkout link-to-pull-request
+```
+
+meaning that you will automatically check out the branch for the pull request,
+without needing any other steps like setting git upstreams! :sparkles:
+
+
+## Thanks
+
+Special thanks to [Hoodie][https://github.com/hoodiehq/hoodie] for the great
+CONTRIBUTING.md template.
+
+[1]: http://mail-archives.apache.org/mod_mbox/couchdb-user/
+[5]: http://mail-archives.apache.org/mod_mbox/couchdb-dev/
+[6]: http://couchdb.apache.org/conduct.html
+[7]: http://couchdb.apache.org/bylaws.html
+[8]: http://couchdb.apache.org/#chat
+
diff --git a/README.rst b/README.rst
index 35adaae..5e435b5 100644
--- a/README.rst
+++ b/README.rst
@@ -1,13 +1,15 @@
Apache CouchDB README
=====================
-Travis CI master build status: |travisci|
++--------------------------------+------------+
+| Travis CI master build status | |travisci| |
++--------------------------------+------------+
+| Jenkins CI master build status | |jenkins| |
++--------------------------------+------------+
.. |travisci| image:: https://travis-ci.org/apache/couchdb.svg?branch=master
:target: https://travis-ci.org/apache/couchdb
-Jenkins CI master build status: |jenkins|
-
.. |jenkins| image:: https://builds.apache.org/buildStatus/icon?job=CouchDB
:target: https://builds.apache.org/job/CouchDB/
@@ -79,6 +81,13 @@ Fauxton. To fix the admin party you have to run ``./dev/run`` with the ``admin``
flag, e.g. ``./dev/run --admin=username:password``. If you want to have an
admin-party, just omit the flag.
+Contributing to CouchDB
+-----------------------
+
+You can learn more about our contributing process here:
+
+ https://github.com/apache/couchdb/blob/master/CONTRIBUTING.md
+
Cryptographic Software Notice
-----------------------------
--
To stop receiving notification emails like this one, please contact
['"commits@couchdb.apache.org" <co...@couchdb.apache.org>'].