From 52c134aed3f4769d56818927cab1f0b6a757d13b Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Thu, 7 Sep 2017 17:48:34 -0300 Subject: [PATCH] Add development guide to docs --- HOWTORELEASE.rst | 12 ++-- doc/en/contents.rst | 1 + doc/en/development_guide.rst | 103 +++++++++++++++++++++++++++++++++++ 3 files changed, 112 insertions(+), 4 deletions(-) create mode 100644 doc/en/development_guide.rst diff --git a/HOWTORELEASE.rst b/HOWTORELEASE.rst index c85fd9b99..48a3461d4 100644 --- a/HOWTORELEASE.rst +++ b/HOWTORELEASE.rst @@ -1,5 +1,9 @@ -How to release pytest --------------------------------------------- +Release Procedure +----------------- + +Our current policy for releasing is to aim for a bugfix every few weeks and a minor release every 2-3 months. The idea +is to get fixes and new features out instead of trying to cram a ton of features into a release and by consequence +taking a lot of time to make a new one. .. important:: @@ -21,7 +25,7 @@ How to release pytest #. Generate docs, changelog, announcements and upload a package to your ``devpi`` staging server:: - invoke generate.pre_release --password + invoke generate.pre-release --password If ``--password`` is not given, it is assumed the user is already logged in ``devpi``. If you don't have an account, please ask for one. @@ -49,7 +53,7 @@ How to release pytest #. Publish to PyPI:: - invoke generate.publish_release + invoke generate.publish-release where PYPI_NAME is the name of pypi.python.org as configured in your ``~/.pypirc`` file `for devpi `_. diff --git a/doc/en/contents.rst b/doc/en/contents.rst index 028414eb6..6b9eed010 100644 --- a/doc/en/contents.rst +++ b/doc/en/contents.rst @@ -41,6 +41,7 @@ Full pytest documentation historical-notes license contributing + development_guide talks projects faq diff --git a/doc/en/development_guide.rst b/doc/en/development_guide.rst new file mode 100644 index 000000000..64a2923b6 --- /dev/null +++ b/doc/en/development_guide.rst @@ -0,0 +1,103 @@ +Development Guide +----------------- + +Some general guidelines regarding development in pytest for core maintainers and general contributors. Nothing here +is set in stone and can't be changed, feel free to suggest improvements or changes in the workflow. + + +Code Style +---------- + +* `PEP-8 `_ +* `flake8 `_ for quality checks +* `invoke `_ to automate development tasks + + +Branches +-------- + +We have two long term branches: + +* ``master``: contains the code for the next bugfix release. +* ``features``: contains the code with new features for the next minor release. + +The official repository usually does not contain topic branches, developers and contributors should create topic +branches in their own forks. + +Exceptions can be made for cases where more than one contributor is working on the same +topic or where it makes sense to use some automatic capability of the main repository, such as automatic docs from +`readthedocs `_ for a branch dealing with documentation refactoring. + +Issues +------ + +Any question, feature, bug or proposal is welcome as an issue. Users are encouraged to use them whenever they need. + +GitHub issues should use labels to categorize them. Labels should be created sporadically, to fill a niche; we should +avoid creating labels just for the sake of creating them. + +Here is a list of labels and a brief description mentioning their intent. + + +**Type** + +* ``type:bug``: problem that needs to be addressed. +* ``type:backward compatibility``: issue that will cause problems with old pytest versions. +* ``type:deprecation``: feature that will be deprecated in the future. +* ``type:docs``: documentation missing or needing clarification. +* ``type:enhancement``: new feature or API change, should be merged into ``features``. +* ``type:feature-branch``: new feature or API change, should be merged into ``features``. +* ``type:infrastructure``: improvement to development/releases/CI structure. +* ``type:performance``: performance or memory problem/improvement. +* ``type:proposal``: proposal for a new feature, often to gather opinions or design the API around the new feature. +* ``type:question``: question regarding usage, installation, internals or how to test something. +* ``type:refactoring``: internal improvements to the code. +* ``type:regression``: indicates a problem that was introduced in a release which was working previously. + +**Status** + +* ``status:critical``: grave problem or usability issue that affects lots of users. +* ``status:easy``: easy issue that is friendly to new contributors. +* ``status:help wanted``: core developers need help from experts on this topic. +* ``status:needs information``: reporter needs to provide more information; can be closed after 2 or more weeks of inactivity. + +**Topic** + +* ``topic: collection`` +* ``topic: fixtures`` +* ``topic: parametrize`` +* ``topic: selection`` +* ``topic: reporting`` +* ``topic: tracebacks`` + +**Plugin (internal or external)** + +* ``plugin: junitxml`` +* ``plugin: cache`` +* ``plugin: capture`` +* ``plugin: doctests`` +* ``plugin: pytester`` +* ``plugin: unittest`` +* ``plugin: warnings`` +* ``plugin: xdist`` + + +**OS** + +Issues specific to a single operating system. Do not use as a means to indicate where an issue originated from, only +for problems that happen **only** in that system. + +* ``os: windows`` +* ``linux: windows`` +* ``mac: windows`` + +**Temporary** + +Used to classify issues for limited time, to help find issues related in events for example. +They should be removed after they are no longer relevant. + +* ``temporary: EP2017 sprint``: +* ``temporary: sprint-candidate``: + + +.. include:: ../../HOWTORELEASE.rst