Overhaul CONTRIBUTING.rst

CONTRIBUTING.rst

@@ -1,80 +1,137 @@
 Contributor Guidelines
 ======================
 
-Contributions are welcome & greatly appreciated, every little bit
+Contributions are welcome and greatly appreciated. Every little bit
-helps in making Hy more awesome.
+helps in making Hy better. Potential contributions include:
 
-Pull requests are great! We love them; here is a quick guide:
+- Reporting bugs
+- Fixing bugs
+- Requesting features
+- Adding features
+- Writing tests for outstanding bugs or untested features
 
-- `Fork the repo`_ and create a topic branch for a feature/fix. Avoid
+  - You can mark tests that Hy can't pass yet as xfail_.
-  making changes directly on the master branch. If you would like to 
+- Cleaning up the code
-  contribute but don't know how to begin, the `good-first-bug`_ label 
+- Improving the documentation
-  of the `issue tracker`_ is the place to go. 
+- Answering questions on `the IRC channel`_, `the mailing list`_, or
-  (If you're new to Git: `Start Here`_)
+  `Stack Overflow`_
+- Evangelizing for Hy in your organization, user group, conference, or
+  bus stop
 
-- Before contributing make sure you check the docs. There are two versions of docs available:
+Issues
+~~~~~~
 
-  + `master`_, for use with the bleeding-edge GitHub version.
+To report bugs or request features, search the `issue tracker`_ to
+check for a duplicate. (If you're reporting a bug, make sure you can
+reproduce it with the very latest, bleeding-edge version of Hy from
+the ``master`` branch on GitHub. Bugs in stable versions of Hy are
+fixed on ``master`` before the fix makes it into a new stable
+release.) Then make a new issue.
 
-  + `stable`_, for use with the PyPI version.
+It's totally acceptable to create an issue when you're unsure whether
+something is a bug or not. We'll help you figure it out.
 
-- All incoming features should be accompanied with tests.
+Use the same issue tracker to report problems with the documentation.
 
-- If you are contributing a major change to the Hy language (e.g. changing
+Pull requests
-  the behavior of or removing functions or macros), or you're unsure of
+~~~~~~~~~~~~~
-  the proposed change, please open an issue in the `issue tracker`_ before
-  submitting the PR. This will allow others to give feedback on your idea,
-  and it will avoid constant changes or wasted work. For other PRs (such as
-  documentation fixes or code cleanup), you can directly open the PR without
-  first opening a corresponding issue.
 
-- Every Python or Hy file in the source tree that is potentially copyrightable
+Submit proposed changes to the code or documentation as pull requests
-  should have the following header (but with ``;;`` in place of ``#`` for Hy
+(PRs) on GitHub_. Git can be intimidating and confusing to the
-  files)::
+uninitiated. `This getting-started guide`_ may be helpful. But if
+you're overwhelmed by Git or GitHub or the rules below, don't sweat
+it; we want to keep the barrier to contribution low, so we're happy to
+help you with these finicky things, or do them for you if necessary.
+
+Deciding what to do
+-------------------
+
+Issues tagged good-first-bug_ are expected to be relatively easy to
+fix, so they may be good targets for your first PR for Hy.
+
+If you're proposing a major change to the Hy language, or you're
+unsure of the proposed change, create an issue to discuss it before
+you write any code. This will allow others to give feedback on your
+idea, and possibly avoid wasted work.
+
+File headers
+------------
+
+Every Python or Hy file in the source tree that is potentially
+copyrightable should have the following header (but with ``;;`` in
+place of ``#`` for Hy files)::
 
       # Copyright [current year] the authors.
       # This file is part of Hy, which is free software licensed under the Expat
       # license. See the LICENSE.
 
-  As a rule of thumb, a file can be considered potentially copyrightable if it
+As a rule of thumb, a file can be considered potentially copyrightable
-  includes at least 10 lines that contain something other than comments or
+if it includes at least 10 lines that contain something other than
-  whitespace. If in doubt, include the header.
+comments or whitespace. If in doubt, include the header.
 
-- Before you submit a PR, please run the tests and check your code
+Commit formatting
-  against the style guide. You can do both of these things at once::
+-----------------
 
-    $ make d
+Many PRs are small enough that only one commit is necessary, but
+bigger ones should be organized into logical units as separate
+commits. PRs should be free of merge commits and commits that fix or
+revert other commits in the same PR (``git rebase`` is your friend).
 
-- Make commits into logical units, so that it is easier to track &
+Avoid committing spurious whitespace changes.
-  navigate later. Before submitting a PR, try squashing the commits
-  into changesets that are easy to come back to later. Also, make sure
-  you don't leave spurious whitespace in the changesets; this avoids
-  creation of whitespace fix commits later.
 
-- As far as commit messages go, try to adhere to the following:
+Format commit messages as follows. The first line should describe the
+overall change in 50 characters or less. If you wish to add more
+information, separate it from the first line with a blank line.
 
-  + Try sticking to the 50 character limit for the first line of Git
+Testing
-    commit messages.
+-------
 
-  + For more detail/explanations, follow this up with a blank line and
+New features and bug fixes should be tested. If you've caused an
-    continue describing the commit in detail.
+xfail_ test to start passing, remove the xfail mark. If you're
+testing a bug that has a GitHub issue, include a comment with the URL
+of the issue.
 
-- Unless your change is very small, like a documentation wording
+No PR may be merged if it causes any tests to fail. You can run the
-  improvement, add an item describing it to the NEWS file.
+test suite and check the style of your code with ``make d``. You can
+purge the byte-compiled versions of the test files with ``git
+clean -dfx tests/`` You can run the tests while skipping the slow
+tests in ``test_bin.py`` with ``pytest --ignore=tests/test_bin.py``.
 
-- Finally, add yourself to the AUTHORS file (as a separate commit): you
+NEWS and AUTHORS
-  deserve it :)
+----------------
 
-- All incoming changes need to be acked by 2 different members of
+If you're making user-visible changes to the code, add one or more
-  Hylang's core team. Additional review is clearly welcome, but we need
+items describing it to the NEWS file.
-  a minimum of 2 signoffs for any change.
 
-- If a core member is sending in a PR, please find 2 core members that doesn't
+Finally, add yourself to the AUTHORS file (as a separate commit): you
-  include the PR submitter. The idea here is that one can work with the PR
+deserve it. :)
-  author, and a second acks the entire change set.
 
-- For documentation & other trivial changes, we're good to merge after one
+The PR itself
-  ACK. We've got low coverage, so it'd be great to keep that barrier low.
+-------------
+
+PRs should ask to merge a new branch that you created for the PR into
+hylang/hy's ``master`` branch, and they should have as their origin
+the most recent commit possible.
+
+If the PR fulfills one or more issues, then the body text of the PR
+(or the commit message for any of its commits) should say "Fixes
+#123" or "Closes #123" for each affected issue number. Use this exact
+(case-insensitive) wording, because when a PR containing such text is
+merged, GitHub automatically closes the mentioned issues, which is
+handy. Conversely, avoid this exact language if you want to mention
+an issue without closing it (because e.g. you've partly but not
+entirely fixed a bug).
+
+Before any PR is merged, it must be approved by one or more members of
+Hy's core team, none of whom may be the author of the PR. Changes to
+the documentation, or trivial changes to code, need to be approved by
+**one** member. All other PRs need to be approved by **two** members.
+
+Anybody may perform the merge. Merging should create a merge commit
+(don't squash, because that would remove separation between logically
+separate commits, and don't fast-forward, because that would throw
+away the history of the commits as a separate branch), which should
+include the PR number in the commit message.
 
 Contributor Code of Conduct
 ===========================
@@ -115,9 +172,10 @@ http://contributor-covenant.org/version/1/1/0/.
 
 .. _Contributor Covenant: http://contributor-covenant.org
 .. _issue tracker: https://github.com/hylang/hy/issues
-.. _Fork the Repo: https://help.github.com/articles/fork-a-repo/
+.. _GitHub: https://github.com/hylang/hy
-.. _Start Here: http://rogerdudler.github.io/git-guide/
+.. _This getting-started guide: http://rogerdudler.github.io/git-guide/
 .. _good-first-bug: https://github.com/hylang/hy/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-bug
-.. _master: http://docs.hylang.org/en/master/
+.. _the IRC channel: irc://freenode.net/hy
-.. _stable: http://hylang.org/
+.. _the mailing list: https://groups.google.com/forum/#!forum/hylang-discuss
-
+.. _Stack Overflow: https://stackoverflow.com/questions/tagged/hy
+.. _xfail: https://docs.pytest.org/en/latest/skipping.html#mark-a-test-function-as-expected-to-fail

docs/hacking.rst

@@ -88,10 +88,6 @@ To build the docs in HTML::
 
 Write docs---docs are good! Even this doc!
 
-
-Contributing
-============
-
 .. include:: ../CONTRIBUTING.rst
 
 Core Team