You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
183 lines
6.7 KiB
ReStructuredText
183 lines
6.7 KiB
ReStructuredText
Development Guide
|
|
=================
|
|
|
|
Consider any rules here *reasonably soft* and significantly at your discretion.
|
|
Do not let a rule prevent you from accomplishing something: work on the
|
|
principle that it is easier to ask forgiveness than permission.
|
|
|
|
|
|
Layering
|
|
--------
|
|
|
|
The repository contains two projects that were developed in tandem primarily
|
|
due to historical incident. Early development was accelerated by working in one
|
|
repository, and while components like ``setup.py`` and the test framework are
|
|
presently shared, the ``ansible_mitogen`` and ``mitogen`` packages are still
|
|
logically independent.
|
|
|
|
The ``ansible_mitogen`` package should depend on the ``mitogen`` package,
|
|
however the ``mitogen`` package must not depend on the ``ansible_mitogen``
|
|
package.
|
|
|
|
|
|
Code Style
|
|
----------
|
|
|
|
Try to conform to house style, but also note there is no precise house style.
|
|
Working code trumps all other concerns.
|
|
|
|
That aside, some general ideas:
|
|
|
|
* Vaguely PEP-8ish overall
|
|
* Black-like use of explicit parenthesis to break up lines and expressions that
|
|
would otherwise wrap
|
|
* Typically max 80 column lines. Code that cannot be diffed side-by-side by a
|
|
semi-blind person on a small laptop display without wrapping will likely be
|
|
reformatted
|
|
* One import per line, with imports sorted and grouped except where wrapped in
|
|
a control structure
|
|
* ``from .. import ..`` for package-internal imports only, use extremely
|
|
sparingly for non-module imports. Unless creating a distinct name for an
|
|
object is explicitly desired, prefer avoiding aliases (``from foo.bar import
|
|
somefunc``) if possible
|
|
* Functions generally should try to avoid exceeding 48 lines in length, except
|
|
where there may be good reason to, such as inlining code used in a hot loop
|
|
* Try to keep every function documented, and tweak the documentation if a
|
|
change modifies the semantics of the function
|
|
* Try to avoid if/else spaghetti in any single function or across a set of functions
|
|
* Try to aggressively split out large sub-functions into their own functions
|
|
* If adding or removing some public function or class, ensure the ``docs/``
|
|
documentation is updated to match
|
|
* Almost all material changes should include a changelog entry
|
|
|
|
|
|
Repository Layout
|
|
-----------------
|
|
|
|
The repository is developed in "traditional Git" style, there is no requirement
|
|
for every change to have an associated pull request, except where it is
|
|
desirable to trigger GitHub features such as CI or to request review.
|
|
|
|
It is expected that Git is used as it were designed, as a graph of patches each
|
|
having their own permanent identity and ancestry, and that they may flow freely
|
|
across branches, in a primarily command-line driven workflow.
|
|
|
|
|
|
Branches
|
|
--------
|
|
|
|
The following branches exist:
|
|
|
|
* ``master``: development branch for the latest major (0.3 as of writing) series
|
|
* ``stable``: release branch for the latest major series
|
|
* ``0.2``: development branch for the 0.2 series
|
|
* ``0.2-stable``: release branch for the 0.2 series
|
|
|
|
|
|
Commit Messages
|
|
---------------
|
|
|
|
Where possible, prefer to include any associated ticket number in commit
|
|
messages, prefixed with ``ticket #123``. For example, instead of:
|
|
|
|
``fix crash in WidgetClass``
|
|
|
|
Write:
|
|
|
|
``ticket #22: fix crash in WidgetClass``
|
|
|
|
This allows straightforward use of ``git blame`` and ``git log`` to immediately
|
|
discover the reason and history behind some change. It also avoids the creating
|
|
a dedicated pull request and merge for each small change to track the
|
|
relationship between commits and tickets, and allows tagging a ticket after any
|
|
PR for it has already been merged.
|
|
|
|
|
|
Commit Descriptions
|
|
-------------------
|
|
|
|
Feel free to use commit message bodies to communicate sundry information about
|
|
a change that is not permanent enough to be a comment, but still of historical
|
|
value. These bodies are distinctly separate from what may appear in a ticket as
|
|
one is user-facing and the other is developer-facing.
|
|
|
|
|
|
Revision History
|
|
----------------
|
|
|
|
Prefer preserving full history of your changes, as this allows precise use of
|
|
most Git tooling (particularly ``blame``, ``cherry-pick`` and ``revert``).
|
|
|
|
Feel free to partially squash away meaningless related changes using ``git
|
|
rebase`` prior to merging to another branch such as the main development
|
|
branch, but avoid this after the changes have been merged somewhere where they
|
|
are or likely will become part of the permanent repository history.
|
|
|
|
|
|
Documentation Branch
|
|
--------------------
|
|
|
|
In order to avoid running CI for documentation changes and tweaks, the
|
|
documentation is built from the ``docs-master`` branch. This branch often drifts
|
|
away from ``master``, but usually just requires a quick merge to bring things
|
|
back to normal.
|
|
|
|
The documentation branch semantics are that it contains whatever it makes sense
|
|
to display on the web. There is no enforced relationship between it and master,
|
|
except that whatever it contains should eventually end up back on ``master``.
|
|
|
|
Automation rebuilds and publishes the ``docs-master`` branch on each commit.
|
|
|
|
Use your discretion if you decide to bypass CI and commit to ``docs-master``
|
|
directly, but if you do, ensure the changes eventually make it back on to
|
|
``master``.
|
|
|
|
|
|
Merging to a development branch
|
|
-------------------------------
|
|
|
|
If you can commit directly to the repository, you have been entrusted with the
|
|
ability to merge to the development branch at your discretion, so long as tests
|
|
are passing and you believe your change to be good.
|
|
|
|
* Adding extensive new functionality should have some accompanying tests, or
|
|
existing tests augmented to tickle the new functionality
|
|
|
|
* Request review using a PR from another contributor if you have some doubt
|
|
about a change
|
|
|
|
Consider requesting review where a change:
|
|
|
|
* Breaks any interface, either API or user-exposed interface
|
|
|
|
* Changes compatibility
|
|
|
|
* Increases dependencies
|
|
|
|
|
|
Release Process
|
|
---------------
|
|
|
|
1. Ensure Changelog is completely up to date with all major changes made since
|
|
the prior release. Use ``git log master..stable`` to determine which commits
|
|
may be missing.
|
|
2. Merge any documentations up to ``docs-master`` branch, and verify
|
|
``docs-master`` is not carrying any changes that are not on ``master``.
|
|
2. `Update __init.py__ <https://github.com/dw/mitogen/commit/153d79b878f6be55bcae63b35bf2b21f545820af>`_
|
|
3. Create PR for appropriate stable branch and get it reviewed by another maintainer
|
|
4. Merge the PR
|
|
5. ``git stash``
|
|
6. ``git checkout stable``
|
|
7. ``git pull``
|
|
8. ``git reset --hard origin/stable``
|
|
9. ``git tag v0.3.123 -a "Mitogen v0.3.123"`` -- tags must be annotated
|
|
10. ``git push --tags``
|
|
11. ``python setup.py sdist bdist_wheel``
|
|
12. [TBD] https://github.com/mitogen-hq/mitogen/issues/771
|
|
13. ``twine upload dist/*.{tar.gz,whl}``
|
|
|
|
Mailing list:
|
|
|
|
1. Run ``python scripts/release-notes.py 0.3.123`` and copy its output
|
|
2. [TBD]
|