From eb9fcac064fec006cb776d17bbcec1bc2b642579 Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Sat, 4 Jun 2016 14:18:44 -0500 Subject: [PATCH] Add contributing documentation --- docs/source/internal/contributing.rst | 200 ++++++++++++++++++++++++++ docs/source/internal/index.rst | 1 + 2 files changed, 201 insertions(+) create mode 100644 docs/source/internal/contributing.rst diff --git a/docs/source/internal/contributing.rst b/docs/source/internal/contributing.rst new file mode 100644 index 0000000..f9feb2e --- /dev/null +++ b/docs/source/internal/contributing.rst @@ -0,0 +1,200 @@ +======================== + Contributing to Flake8 +======================== + +We encourage multiple methods of participation in Flake8: + +- contributing bug reports and feature requests + +- contributing documenation (and yes that includes this document) + +- reviewing and triaging bugs and merge requests + +Before you go any further, please allow me to reassure you that I do want +*your* contribution. If you think your contribution might not be valuable, I +reassure you that any help you can provide *is* valuable. + + +Code of Conduct +=============== + +Flake8 adheres to the `Python Code Quality Authority's Code of Conduct`_. +Any violations of the Code of Conduct should be reported to Ian Cordasco +(graffatcolmingov [at] gmail [dot] com). + + +Setting Up A Development Environment +==================================== + +To contribute to Flake8's development, you simply need: + +- Python (one of the versions we support) + +- `tox`_ + + We suggest installing this like: + + .. prompt:: bash + + pip install --user tox + + Or + + .. prompt:: bash + + python -m pip install --user tox + +- and your favorite editor + + +Filing a Bug +============ + +When filing a bug against Flake8, please fill out the issue template as it is +provided to you by `GitLab`_. If your bug is in reference to one of the +checks that Flake8 reports by default, please do not report them to Flake8 +unless Flake8 is doing something to prevent the check from running or you +have some reason to believe Flake8 is inhibiting the effectiveness of the +check. + +**Please search for closed and open bug reports before opening new ones.** + +All bug reports about checks should go to their respective projects: + +- Check codes starting with ``E`` and ``W`` should be reported to + `pycodestyle`_. + +- Check codes starting with ``F`` should be reported to `pyflakes`_ + +- Check codes starting with ``C`` should be reported to `mccabe`_ + + +Requesting a New Feature +======================== + +When requesting a new feature in Flake8, please fill out the issue template. +Please also note if there are any existing alternatives to your new feature +either via plugins, or combining command-line options. Please provide example +use cases. For example, do not ask for a feature like this: + + I need feature frobulate for my job. + +Instead ask: + + I need Flake8 to frobulate these files because my team expects them to + frobulated but Flake8 currently does not frobulate them. We tried using + ``--filename`` but we could not create a pattern that worked. + +The more you explain about *why* you need a feature, the more likely we are to +understand your needs and help you to the best of our ability. + + +Contributing Documentation +========================== + +To contribute to Flake8's documentation, you should first familiarize yourself +with reStructuredText and Sphinx. For the most part, you should be fine +following the structure and style of the rest of Flake8's documentation. + +All of Flake8's documentation is written in reStructuredText and rendered by +Sphinx. The source (reStructuredText) lives in ``docs/source/``. To build +the documentation the way our Continuous Integration does, run: + +.. prompt:: bash + + tox -e docs + +To view the documentation locally, you can also run: + +.. prompt:: bash + + tox -e serve-docs + +You can run the latter in a separate terminal and continuously re-run the +documentation generation and refresh the documentation you're working on. + +.. note:: + + We lint our documentation just like we lint our code. + You should also run: + + .. prompt:: bash + + tox -e linters + + After making changes and before pushing them to ensure that they will + pass our CI tests. + + +Contributing Code +================= + +Flake8 development happens on `GitLab`_. Code contributions should be +submitted there. + +Merge requests should: + +- Fix one issue and fix it well + + Fix the issue, but do not include extraneous refactoring or code + reformatting. In other words, keep the diff short, but only as short + as is necessary to fix the bug appropriately and add sufficient testing + around it. Long diffs are fine, so long as everything that it includes + is necessary to the purpose of the merge request. + +- Have descriptive titles and descriptions + + Searching old merge requests is made easier when a merge request is well + described. + +- Have commits that follow this style: + + .. code:: + + Create a short title that is 50 characters long + + Ensure the title and commit message use the imperative voice. The + commit and you are doing something. Also, please ensure that the + body of the commit message does not exceed 72 characters. + + The body may have multiple paragraphs as necessary. + + The final line of the body references the issue appropriately. + + +Reviewing and Triaging Issues and Merge Requests +================================================ + +When reviewing other people's merge requests and issues, please be +**especially** mindful of how the words you choose can be ready by someone +else. We strive for professional code reviews that do not insult the +contributor's intelligence or impugn their character. The code review +should be focused on the code, it's effectiveness, and whether it is +appropriate for Flake8. + +If you have the ability to edit an issue or merge request's labels, please do +so to make search and prioritization easier. + +Flake8 uses milestones with both issues and merge requests to provide +other contributors direction about when an issue or merge request will be +delivered. + + +.. links +.. _Python Code Quality Authority's Code of Conduct: + http://meta.pycqa.org/en/latest/code-of-conduct.html + +.. _tox: + https://tox.readthedocs.io/ + +.. _GitLab: + https://gitlab.com/pycqa/flake8 + +.. _pycodestyle: + https://github.com/pycqa/pycodestyle + +.. _pyflakes: + https://github.com/pyflakes/pyflakes + +.. _mccabe: + https://github.com/pycqa/mccabe diff --git a/docs/source/internal/index.rst b/docs/source/internal/index.rst index 4220fe9..81efa2c 100644 --- a/docs/source/internal/index.rst +++ b/docs/source/internal/index.rst @@ -15,6 +15,7 @@ pull gently. .. toctree:: :maxdepth: 2 + contributing checker cli formatters