Yaltik/hy
2
0
Fork 0
Code Pull Requests Releases Activity

Merge pull request #1300 from Kodiologist/contributing

Browse Source 
Overhaul CONTRIBUTING.rst
This commit is contained in:
Kodi Arfer 2017-06-14 14:08:34 -07:00 committed by GitHub
commit d86381ff98
3 changed files with 113 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

166
CONTRIBUTING.rst
View File

@ -1,80 +1,135 @@
Contributor Guidelines
======================
Contributions are welcome & greatly appreciated, every little bit
helps in making Hy more awesome.
Contributions are welcome and greatly appreciated. Every little bit
helps in making Hy better. Potential contributions include:
Pull requests are great! We love them; here is a quick guide:
- Reporting and fixing bugs.
- Requesting features.
- Adding features.
- Writing tests for outstanding bugs or untested features.
- You can mark tests that Hy can't pass yet as xfail_.
- Cleaning up the code.
- Improving the documentation.
- Answering questions on `the IRC channel`_, `the mailing list`_, or
`Stack Overflow`_.
- Evangelizing for Hy in your organization, user group, conference, or
bus stop.
- `Fork the repo`_ and create a topic branch for a feature/fix. Avoid
making changes directly on the master branch. If you would like to
contribute but don't know how to begin, the `good-first-bug`_ label
of the `issue tracker`_ is the place to go.
(If you're new to Git: `Start Here`_)
Issues
~~~~~~
- Before contributing make sure you check the docs. There are two versions of docs available:
In order 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.) If there aren't any duplicates, then you can make a new issue.
+ `master`_, for use with the bleeding-edge GitHub 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.
+ `stable`_, for use with the PyPI version.
Use the same issue tracker to report problems with the documentation.
- All incoming features should be accompanied with tests.
Pull requests
~~~~~~~~~~~~~
- If you are contributing a major change to the Hy language (e.g. changing
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.
Submit proposed changes to the code or documentation as pull requests
(PRs) on GitHub_. Git can be intimidating and confusing to the
uninitiated. `This getting-started guide`_ may be helpful. However, if
you're overwhelmed by Git, 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.
- 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)::
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 it can 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
includes at least 10 lines that contain something other than comments or
whitespace. If in doubt, include the header.
As a rule of thumb, a file can be considered potentially copyrightable
if it includes at least 10 lines that contain something other than
comments or whitespace. If in doubt, include the header.
- Before you submit a PR, please run the tests and check your code
against the style guide. You can do both of these things at once::
Commit formatting
-----------------
$ 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 &
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.
Avoid committing spurious whitespace changes.
- As far as commit messages go, try to adhere to the following:
The first line of a commit message 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
commit messages.
Testing
-------
+ For more detail/explanations, follow this up with a blank line and
continue describing the commit in detail.
New features and bug fixes should be tested. If you've caused an
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
improvement, add an item describing it to the NEWS file.
No PR may be merged if it causes any tests to fail. You can run the
test suite and check the style of your code with ``make d``. The byte-compiled
versions of the test files can be purged using ``git clean -dfx tests/``.
If you want to run the tests while skipping the slow ones in ``test_bin.py``,
use ``pytest --ignore=tests/test_bin.py``.
- Finally, add yourself to the AUTHORS file (as a separate commit): you
deserve it :)
NEWS and AUTHORS
----------------
- All incoming changes need to be acked by 2 different members of
Hylang's core team. Additional review is clearly welcome, but we need
a minimum of 2 signoffs for any change.
If you're making user-visible changes to the code, add one or more
items describing it to the NEWS file.
- If a core member is sending in a PR, please find 2 core members that doesn't
include the PR submitter. The idea here is that one can work with the PR
author, and a second acks the entire change set.
Finally, add yourself to the AUTHORS file (as a separate commit): you
deserve it. :)
- For documentation & other trivial changes, we're good to merge after one
ACK. We've got low coverage, so it'd be great to keep that barrier low.
The PR itself
-------------
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 members of Hy's core team
other than the PR's author. 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 on the team may perform the merge. Merging should create a merge commit
(don't squash unnecessarily, 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 +170,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/
.. _Start Here: http://rogerdudler.github.io/git-guide/
.. _GitHub: https://github.com/hylang/hy
.. _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/
.. _stable: http://hylang.org/
.. _the IRC channel: irc://freenode.net/hy
.. _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

2
LICENSE
View File

@ -1,3 +1,5 @@
Copyright 2017 the authors.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation

4
docs/hacking.rst
View File

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