diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..1ef4ea2 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,77 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at report@nucypher.com. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see +https://www.contributor-covenant.org/faq + diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 0000000..f832ab0 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,219 @@ +Contributing +============ + +.. image:: https://cdn-images-1.medium.com/max/800/1*J31AEMsTP6o_E5QOohn0Hw.png + :target: https://cdn-images-1.medium.com/max/800/1*J31AEMsTP6o_E5QOohn0Hw.png + + +Acquiring the Codebase +---------------------- + +.. _`pyUmbral GitHub`: https://github.com/nucypher/pyUmbral + +In order to contribute new code or documentation changes, you will need a local copy +of the source code which is located on the `pyUmbral GitHub`_. + +.. note:: + + pyUmbral uses ``git`` for version control. Be sure you have it installed. + +Here is the recommended procedure for acquiring the code in preparation for +contributing proposed changes: + + +1. Use GitHub to Fork the `nucypher/pyUmbral` repository + +2. Clone your fork's repository to your local machine + +.. code-block:: bash + + $ git clone https://github.com//pyUmbral.git + +3. Change Directories into ``pyUmbral`` + +.. code-block:: bash + + cd pyUmbral + +3. Add `nucypher/pyUmbral` as an upstream remote + +.. code-block:: bash + + $ git remote add upstream https://github.com/nucypher/pyUmbral.git + +4. Update your remote tracking branches + +.. code-block:: bash + + $ git remote update + +5. Install pyUmbral + +.. code-block:: bash + + $ pip3 install umbral + + +Running the Tests +----------------- + +.. _Pytest Documentation: https://docs.pytest.org/en/latest/ + +pyUmbral tests are written for execution with ``pytest``. +For more details see the `Pytest Documentation`_. + +To run the tests: + +.. code:: bash + + (pyUmbral)$ pytest + + +Making A Commit +--------------- + +NuCypher takes pride in its commit history. + +When making a commit that you intend to contribute, keep your commit descriptive and succinct. +Commit messages are best written in full sentences that make an attempt to accurately +describe what effect the changeset represents in the simplest form. (It takes practice!) + +Imagine you are the one reviewing the code, commit-by-commit as a means of understanding +the thinking behind the PRs history. Does your commit history tell an honest and accurate story? + +We understand that different code authors have different development preferences, and others +are first-time contributors to open source, so feel free to join our `Discord `_ and let us know +how we can best support the submission of your proposed changes. + + +Opening A Pull Request +---------------------- + +When considering including commits as part of a pull request into `nucypher/pyUmbral`, +we *highly* recommend opening the pull request early, before it is finished with +the mark "[WIP]" prepended to the title. We understand PRs marked "WIP" to be subject to change, +history rewrites, and CI failures. Generally we will not review a WIP PR until the "[WIP]" marker +has been removed from the PR title, however, this does give other contributors an opportunity +to provide early feedback and assists in facilitating an iterative contribution process. + + +Pull Request Conflicts +---------------------- + +As an effort to preserve authorship and a cohesive commit history, we prefer if proposed contributions +are rebased over master (or appropriate branch) when a merge conflict arises, +instead of making a merge commit back into the contributors fork. + +Generally speaking the preferred process of doing so is with an `interactive rebase`: + +.. important:: + + Be certain you do not have uncommitted changes before continuing. + +1. Update your remote tracking branches + +.. code-block:: bash + + $ git remote update + ... (some upstream changes are reported) + +2. Initiate an interactive rebase over `nucypher/pyUmbral@master` + +.. note:: + + This example specifies the remote name ``upstream`` for the NuCypher organizational repository as + used in the `Acquiring the Codebase`_ section. + +.. code-block:: bash + + $ git rebase -i upstream/master + ... (edit & save rebase TODO list) + +3. Resolve Conflicts + +.. code-block:: bash + + $ git status + ... (resolve local conflict) + $ git add path/to/resolved/conflict/file.py + $ git rebase --continue + ... ( repeat as needed ) + + +4. Push Rebased History + +After resolving all conflicts, you will need to force push to your fork's repository, since the commits +are rewritten. + +.. warning:: + + Force pushing will override any changes on the remote you push to, proceed with caution. + +.. code-block:: bash + + $ git push origin my-branch -f + + +Building Documentation +---------------------- + +.. note:: + + ``sphinx`` is a non-standard dependency that can be installed + by running ``pip install -e .[docs]`` from the project directory. + + +.. _Read The Docs: https://pyumbral.readthedocs.io/en/latest/ + +Documentation for ``pyUmbral`` is hosted on `Read The Docs`_, and is automatically built without intervention by +following the release procedure. However, you may want to build the documentation html locally for development. + +To build the project dependencies locally: + +.. code:: bash + + (pyUmbral)$ cd pyUmbral/docs/ + (pyUmbral)$ make html + + +If the build is successful, the resulting html output can be found in ``pyUmbral/docs/build/html``; +Opening ``pyUmbral/docs/build/html/index.html`` in a web browser is a reasonable next step. + + +Issuing a New Release +--------------------- + +.. note:: + + ``bumpversion`` is a non-standard dependency that can be installed by running ``pip install -e .[deployment]`` or ``pip install bumpversion``. + +.. important:: + + Ensure your local tree is based on ``master`` and has no uncommitted changes. + +1. Increment the desired version part (options are ``major``, ``minor``, ``patch``, ``stage``, ``devnum``), for example: + +.. code:: bash + + (pyUmbral)$ bumpversion devnum + +3. Ensure you have the intended history and incremented version tag: + +.. code:: bash + + (pyUmbral)$ git log + +4. Push the resulting tagged commit to the originating remote by tag and branch to ensure they remain synchronized. + +.. code:: bash + + (pyUmbral)$ git push origin master && git push origin + +5. Push the tag directly upstream by its name to trigger the publication webhooks on CircleCI: + +.. code:: bash + + (pyUmbral)$ git push upstream + +7. Monitor the triggered deployment build on CircleCI for manual approval. +8. Open a pull request with the resulting history in order to update ``master``.