From 8bed805ab44c54df593850393f0afbc14303c51b Mon Sep 17 00:00:00 2001 From: "P. Raj Kumar" Date: Sun, 22 Oct 2017 23:23:35 -0700 Subject: [PATCH] Add contribution guide, code of conduct, authors file, and pull request template (#6) * Add contribution guide * Add ``AUTHORS.rst`` * Add code of conduct * Add pull request template * Make docs use version in `uplink.__about__` * Update contribution guide * Update README * Update preview note on documentation homepage * Bump patch version * Update changelog * Update CONTRIBUTING.rst * Update AUTHORS.rst --- .github/PULL_REQUEST_TEMPLATE.md | 8 ++ AUTHORS.rst | 6 + CHANGELOG.rst | 21 +++- CODE_OF_CONDUCT.md | 73 ++++++++++++ CONTRIBUTING.rst | 196 +++++++++++++++++++++++++++++++ README.rst | 20 +++- docs/source/conf.py | 6 +- docs/source/index.rst | 10 +- uplink/__about__.py | 2 +- 9 files changed, 329 insertions(+), 13 deletions(-) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 AUTHORS.rst create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.rst diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..18dcc90f --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,8 @@ +Fixes # . + +Changes proposed in this pull request: +- +- +- + +Attention: @prkumar \ No newline at end of file diff --git a/AUTHORS.rst b/AUTHORS.rst new file mode 100644 index 00000000..1df0ed04 --- /dev/null +++ b/AUTHORS.rst @@ -0,0 +1,6 @@ +Maintainers +*********** +- Raj Kumar (`@prkumar `_) + +Contributors +************ diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 3836f9ae..bcd1e205 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -6,9 +6,24 @@ All notable changes to this project will be documented in this file. The format is based on `Keep a Changelog`_, and this project adheres to the `Semantic Versioning`_ scheme. +0.1.1_ - 2017-10-21 +=================== +Added +----- +- Contribution guide, ``CONTRIBUTING.rst``. +- "Contributing" Section in README.rst that links to contribution guide. +- ``AUTHORS.rst`` file for listing project contributors. +- Adopt `Contributor Covenant Code of Conduct`_. + +.. _`Contributor Covenant Code of Conduct`: https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +Changed +------- +- Replaced tentative contributing instructions in preview notice on + documentation homepage with link to contribution guide. + 0.1.0 - 2017-10-19 ================== - Added ----- - Python ports for almost all method and argument annotations in Retrofit_. @@ -24,4 +39,6 @@ Added .. _Retrofit: http://square.github.io/retrofit/ .. _`Keep a Changelog`: http://keepachangelog.com/en/1.0.0/ -.. _`Semantic Versioning`: https://packaging.python.org/tutorials/distributing-packages/#semantic-versioning-preferred \ No newline at end of file +.. _`Semantic Versioning`: https://packaging.python.org/tutorials/distributing-packages/#semantic-versioning-preferred + +.. _0.1.1: https://github.com/olivierlacan/keep-a-changelog/compare/v0.1.0...v0.1.1 \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..0c08d40d --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,73 @@ +# 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, gender identity and expression, level of experience, +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 raj.pritvi.kumar@gmail.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 diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 00000000..71d037c6 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,196 @@ +How to Contribute to Uplink +*************************** + +The following is a guide for contributing to Uplink. Thanks for taking the +time to improve an open source project! + +This guide is a work in progress. So, if you have suggestions for +improving the contributors' experience, the release process, or really +anything concerning the source code's management, please feel free to +contact `@prkumar `_ directly. + +Reporting Bugs and Making Feature Requests +========================================== + +We use the GitHub issue tracker for wrangling bug reports and feature requests. +Before you open an issue, please do a quick search against both **closed and +open** issues to ensure that the defect or feature request has not been +reported already. + +Feature Requests +---------------- +As the project is in initial development, we are accepting feature request! +To request a feature, open a GitHub issue, summarize the enhancement, and add +the "feature request" label! + +Making Changes to the Source +============================ + +Changes to the source code typically address one of the following: + +* `Feature enhancement or minor bug fix`_ +* `Critical bug fix`_ + +And, a unit of development typically follows this workflow: + +1. Fork the repository if you don't have write-access. +2. Make your changes, adhering to the `style guide`_. +3. Add or update testing_. +4. Update documentation, if necessary. +5. Add yourself to AUTHORS.rst. +6. When your changes are ready for review, open a `pull request`_. +7. Merge changes. + +Development Process +=================== + +In this section, we'll outline the various development stages of Uplink. +Moreover, we use the GitFlow branching model for Uplink, and as the development +process and branching model go hand-in-hand, we'll cover how GitFlow ties into +each stage. + +To start off, we'll cover the two, everlasting branches: ``master`` and +``develop``. + +``master`` +---------- + +This branch is the most stable branch. Nominally, ``master`` +strictly contains merge commits, each tagged with a release version (e.g, +``v0.1.0``). See releases_ for more on how we handle the releasing +process. + +You can read about the `master branch +`_ +in the linked GitFlow article. + +``develop`` +----------- + +This branch contains work-in-progress for the next immediate release. +You can read about the `develop branch +`_ +in the linked GitFlow article.. + +Feature Enhancement or Minor Bug Fix +------------------------------------ + +Subject to inclusion in some future release, features are logically cohesive +units of work that add value to Uplink. In like manner, a +non-critical bug fix adds value in that it addresses a value destroying +characteristic of the code, a defect. Further, a minor bug is a +defect that we can wait to patch in a different version. A defect that +requires immediate attention needs a `critical bug fix`_. + +Development of a feature or a minor bug fix should happen on a +feature branch, which contains work for the next or some distant +release. Feature development typically looks like: + +1. Branch off of ``develop``. Preferably, prefix the branch name with + ``feature/`` (or ``feature/v{version}/``, where {version} is the feature's + target release version -- e.g., ``feature/v1.0.0/*``) for clarity. +2. Make your changes. +3. If your changes are not targeted for the next immediate release, keep them + on the feature branch until the release branch is cut (see releases_). +4. Once you're done making changes, it's time to merge into develop: + + - Substantial changes require opening a `pull request`_. + - Always **squash and merge**. + +5. If the ``develop`` branch fails the Travis CI or Coveralls builds that run + immediately after your feature merge, revert the squashed merge commit. + Address the issue locally -- i.e., go back to step 2. +6. Delete the feature branch. + +You can read more about `feature branches +`_ +in the linked GitFlow article. + +Critical Bug Fix +---------------- + +To fix a critical bug that affects the latest released version of Uplink and +requires immediate action (i.e., we can't wait and fix it in the next +release), we'll need to: + +1. Create a hotfix branch off ``master``. +2. Increment the version number. +3. Implement a fix. +4. Open `pull request`_ against ``develop``, and another against ``master``. + +You can read more about `hotfix branches +`_ +in the linked GitFlow article. + +Releases +-------- + +Once we're ready to begin the release process, we'll create a release branch +off an appropriate commit of ``develop``. The name of a release branch +should follow the pattern ``release/v{version}``, where ``{version}`` is the +target release version number (e.g., ``release/v1.0.0``). + +Once the release branch is merged into ``master``, we consider the release +completed. However, up until this point, we can make necessary changes to +the release branch, while normal feature development continues on ``develop``. + +When merging the release branch into ``master``, be sure to **squash and +merge**. After merging, create a tag named ``v{version}``, where +``{version}`` is the target release version number (e.g., ``v1.0.0``), +on the the merge commit in ``master``. Tagging the commit prompts Travis +CI to deploy the latest release to PyPI. + +You can read more about `release branches +`_ +in the linked GitFlow article. Notably, before removing a release branch, we'll +need to merge the branch into ``develop`` to incorporate commits made after the +release branch was cut. Moreover, once a release branch is cut, we need to bump +the version number on ``develop``. + +.. _`pull request`: + +Pull Request +============ + +Depending on the type of change you are making, the branching model may +require merging your work into one or two target branches (typically one is +``develop``). Be sure to open a pull request for each target branch. + +1. Open a pull request (PR) to merge your forked branch, the + **candidate**, into **target** branch of this repository. +2. Add Raj (``prkumar``) as a reviewer. +3. If your PR fails the Travis CI check, investigate the build log for + cause of failure, address locally, and update the candidate branch. Repeat + this step until the PR passes the Travis CI check. +4. If your PR fails the Coveralls check, check the PR's Coveralls' report + to identify modules experiencing a test coverage drop. Improve testing + locally, then update the candidate branch. +5. Once all checks have passed and the assigned reviewers have approved, + your changes will be **squashed and merged** into the target branch. + +.. _tests: + +Testing +======= + +We use the unit testing framework ``pytest``. Kept under the `tests` +directory, unit tests are written in Python modules with the filename +pattern ``test_*.py``. + +Notably, ``conftest.py`` defines several `pytest fixtures +`_, for injecting an +instance of an interface (defined in ``uplink.interfaces``) or utility +(defined in ``uplink.helpers``) class into your tests. + +Style Guide +=========== + +To maintain a consistent code style with the rest of Uplink, follow the `Google +Python Style Guide`_. + +Notably, we use a Sphinx plugin that can parse docstrings adherent to this +style. Checkout `this page +`_ +for examples of Google Python Style Guide docstrings. + +.. _`Google Python Style Guide`: https://google.github.io/styleguide/pygu diff --git a/README.rst b/README.rst index d54e0bb3..7af2d21e 100644 --- a/README.rst +++ b/README.rst @@ -60,18 +60,34 @@ accessing HTTP webservices, with minimal code and user pain ☺️. Installation ------------ -``uplink`` supports Python 2.7 & 3.3-3.7. To install the package, you can use -``pip``: +``uplink`` supports Python 2.7 & 3.3-3.7. + +To install the latest stable release, you can use ``pip``: :: $ pip install uplink + +Interested in the cutting-edge? You can install the work-in-progress for the +upcoming release with: + +:: + + $ pip install https://github.com/prkumar/uplink/archive/develop.zip + Documentation ------------- For more details, check out the documentation at http://uplink.readthedocs.io/. +Contributing +------------ + +Looking to report a bug, request a feature, or contribute code to Uplink? +Checkout the `Contribution Guide `_ ! Thanks for taking +the time to improve an open source project! + .. |Build Status| image:: https://travis-ci.org/prkumar/uplink.svg?branch=master :target: https://travis-ci.org/prkumar/uplink .. |Coverage Status| image:: https://coveralls.io/repos/github/prkumar/uplink/badge.svg?branch=master diff --git a/docs/source/conf.py b/docs/source/conf.py index c65ba07a..bc5788f8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -20,6 +20,8 @@ # import sys # sys.path.insert(0, os.path.abspath('.')) +# Import package metadata +from uplink.__about__ import __version__ # -- General configuration ------------------------------------------------ @@ -61,9 +63,9 @@ # built documents. # # The short X.Y version. -version = u'0.1' +version = __version__ # The full version, including alpha/beta/rc tags. -release = u'0.1.0' +release = __version__ # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/source/index.rst b/docs/source/index.rst index e2f3c7f9..f1c3a3d9 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -23,13 +23,11 @@ A Declarative HTTP Client for Python. Inspired by `Retrofit opening a GitHub issue when you notice a missing feature, latent defect, documentation oversight, etc. - Moreover, for those interested in contributing, I plan to publish a - contribution guide soon, but in the meantime, please feel free to fork - the `repository on GitHub `__ and open - a pull request ('tis - `Hacktoberfest `__, after all)! + Moreover, for those interested in contributing, checkout the `Contribution + Guide on GitHub`_ ('tis `Hacktoberfest`__, after all)! ----- +.. _`Contribution Guide on GitHub`: https://github.com/prkumar/uplink/blob/master/CONTRIBUTING.rst +.. _Hacktoberfest: https://hacktoberfest.digitalocean.com/ A Quick Walkthrough, with GitHub API v3: ---------------------------------------- diff --git a/uplink/__about__.py b/uplink/__about__.py index 9c895f4d..10b4088c 100644 --- a/uplink/__about__.py +++ b/uplink/__about__.py @@ -3,4 +3,4 @@ that is used both in distribution (i.e., setup.py) and within the codebase. """ -__version__ = "0.1.0" +__version__ = "0.1.1"