Update sphinx documentation

README.md

@@ -57,7 +57,7 @@ See details here:
 
 * [GitHub releases](https://github.com/roc-streaming/roc-toolkit/releases)
 * [Changelog](https://roc-streaming.org/toolkit/docs/development/changelog.html)
-* [Version control](https://roc-streaming.org/toolkit/docs/development/version_control.html)
+* [Development workflow](https://roc-streaming.org/toolkit/docs/development/workflow.html)
 
 Platforms
 ---------

docs/sphinx/development.rst

@@ -8,5 +8,6 @@ Development
    development/roadmap
    development/contribution_guidelines
    development/coding_guidelines
-   development/version_control
+   development/workflow
+   development/maintainer_notes
    development/continuous_integration

docs/sphinx/development/contribution_guidelines.rst

@@ -18,7 +18,7 @@ How you can help
 
 * **Writing**
 
-  If you've built Roc for a niche OS or hardware, or tweaked settings to make it work better for your needs, we'd love if you share your experience with the community. If you wrote a guide, you can send it to us to be added to the :doc:`publications page </about_project/publications>`.
+  If you've built Roc for a niche OS or hardware, or tweaked settings to make it work better for your needs, or used it in your project, we'd love if you share your experience with the community. If you wrote a post, you can send it to us to be added to the :doc:`publications page </about_project/publications>`.
 
 Becoming a contributor
 ======================
@@ -58,8 +58,8 @@ The guide bellow will help you to prepare your first patch.
 
 * **Step 5: Create pull request!**
 
-  Please remember that pull requests should be always rebased on ``develop`` branch and should be targeted to it, as :doc:`described here </development/version_control>`.
+  See :doc:`/development/workflow` page for rules of pull request creation and its life-cycle.
 
-  Before submitting PR, don't forget to run code formatting, as described in coding guidelines.
+  Please remember that pull requests should be always rebased on ``develop`` branch and should be targeted to it!
 
-  Please ensure that all CI checks pass on your PR and fix them if needed.
+  Before submitting PR, don't forget to run code formatting, as described in coding guidelines. After submitting, ensure that all CI checks pass on your PR and fix them if needed.

docs/sphinx/development/maintainer_notes.rst

@@ -0,0 +1,137 @@
+Maintainer notes
+****************
+
+.. contents:: Table of contents:
+   :local:
+   :depth: 1
+
+Merging pull request
+====================
+
+Pull requests should be merged using `pr.py <https://github.com/roc-streaming/roc-toolkit/blob/develop/scripts/pr.py>`_ script, which does the following:
+
+- Rebases PR on up-to-date develop branch.
+- If requested, squashes all commits into one.
+- Overwrites commit messages to add a link to related issue to each commit (e.g. "Implement feature" becomes "gh-123 Implement feature"). The issue number should be present is PR description or passed as command-line flag.
+-  Force-pushes updated commits to PR's branch.
+- Asks GitHub to merge PR.
+
+You should choose whether to merge by rebasing or squashing.
+
+Merge PR by rebasing:
+
+.. code::
+
+   scripts/pr.py merge --rebase 123
+
+Merge PR by rebasing and squashing all commits into one:
+
+.. code::
+
+   scripts/pr.py merge --squash 123
+
+If PR description doesn't have a link to issue, the script will complain and fail. You can manually specify it:
+
+.. code::
+
+   scripts/pr.py merge --rebase 123 --issue 456
+
+The script will use given issue for commits and also will add it to PR description.
+
+Show PR info before merging it:
+
+.. code::
+
+   scripts/pr.py show 123
+
+Link PR commits to issue and force-push to PR's branch, but don't merge PR:
+
+.. code::
+
+   scripts/pr.py link 123
+
+Revert that:
+
+.. code::
+
+   scripts/pr.py unlink 123
+
+For the full list of available options, see:
+
+.. code::
+
+   scripts/pr.py [command] --help
+
+Rebasing develop on master
+==========================
+
+This is usually done before making release. It's needed only if some commits were cherry-picked to ``master`` after ``develop`` was rebased last time.
+
+Update branches:
+
+.. code::
+
+   git switch master && git pull origin master
+   git switch develop && git pull origin develop
+
+Rebase ``develop`` on ``master``:
+
+.. code::
+
+   scripts/rebase.sh master
+
+Push to your fork:
+
+.. code::
+
+   git push -f <your fork> develop
+
+When CI on your fork passes, push to origin:
+
+.. code::
+
+   git push -f origin develop
+
+Updating master to develop
+==========================
+
+Before doing this, first ensure that branches are up-to-date and ``develop`` is rebased on ``master``.
+
+Then fast-forward ``master`` to ``develop``:
+
+.. code::
+
+   git switch master
+   git merge --ff-only develop
+
+Creating release
+================
+
+Rename ``next`` milestone to ``v1.2.3`` and close it. Create new ``next`` milestone.
+
+Add new release to :doc:`changelog page </development/changelog>`.
+
+Update version number in `version header <https://github.com/roc-streaming/roc-toolkit/blob/develop/src/public_api/include/roc/version.h>`_.
+
+Update specs for debian and rpm packages:
+
+.. code::
+
+   scripts/update_packages.py
+
+Update authors page:
+
+.. code::
+
+   scripts/update_authors.sh
+
+Create and push tag:
+
+.. code::
+
+   git tag v1.2.3
+   git push origin v1.2.3
+
+When CI passes, go to `releases page <https://github.com/roc-streaming/roc-toolkit/releases>`_, add links to changelog and milestone to release description, and publish release.
+
+Post announcement to matrix and, in case of big releases, to the mailing list.

docs/sphinx/development/workflow.rst

@@ -0,0 +1,57 @@
+Development workflow
+********************
+
+.. contents:: Table of contents:
+   :local:
+   :depth: 1
+
+Branches
+========
+
+The following branches are used:
+
+* ``master`` -- Stable and ready-to-use branch **for users**. Merged to this branch are tested on all supported platforms. Public releases are tagged from this branch.
+
+* ``develop`` -- Unstable branch **for developers**. Is not regularly tested besides CI and may be sometimes broken. From time to time it is considered ready and merged into the master branch.
+
+Releases
+========
+
+See `Releases <https://github.com/roc-streaming/roc-toolkit/releases>`_ and :doc:`/development/changelog` pages for the list of releases and their detailed description.
+
+Releases are **tagged from master** branch and named according to the `semantic versioning <https://semver.org/>`_ rules:
+
+* patch version Z (x.y.Z) is incremented when introducing backwards-compatible bug fixes;
+* minor version Y (x.Y.z) is incremented when introducing backwards-compatible features;
+* major version X (X.y.z) is incremented when introducing backwards-incompatible changes.
+
+Prior to 1.0.0 release, which hasn't happened yet, there is no compatibility promise for the public API. Small breaking changes are possible in any release.
+
+History
+=======
+
+History in ``master`` and ``develop`` branches is **kept linear**. Only fast-forward merges and rebases are used.
+
+New changes always reach ``develop`` branch first. Sometimes, specific commits may be cherry-picked from ``develop`` to ``master`` if quick bug-fix release is needed. Eventually ``develop`` branch is rebased on ``master``, and ``master`` is fast-forwarded to ``develop`` branch head. Usually this is done before release.
+
+Pull requests
+=============
+
+All pull-requests should be **targeted to develop** branch. Pull request should be rebased on the latest commit from that branch.
+
+It's recommended to group independent changes, like formatting, refactoring, bug fixes, and new features into separate commits. Bonus points if build and tests pass on every commit. This helps a lot when bisecting a regression.
+
+To be merged, a pull request should pass the  :doc:`continuous integration </development/continuous_integration>` checks and code review.
+
+Review cycle
+============
+
+The following labels are used during code review to indicate pull request state:
+
+- ``work in progress`` -- author is doing changes and maintainer should not do review
+- ``ready for review`` -- author have finished doing changes and requests review from maintaner
+- ``review in progress`` -- maintainer started doing review; used when review can take long time, e.g. a few days
+- ``needs revision`` -- maintainer finished review and requested updates or clarifications from author
+- ``needs rebase`` -- automatically added when CI detects that there are unresolved conflicts; author should rebase PR on fresh develop branch
+
+When you have finished doing changes in PR, please **don't forget to "request review"** using corresponding button, or just leave a comment. Otherwise maintainers don't know whether pull request is ready for (re-)review or not.