diff --git a/README.md b/README.md index 223ac2428..1d5b5dc2f 100644 --- a/README.md +++ b/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 --------- diff --git a/docs/sphinx/development.rst b/docs/sphinx/development.rst index f68bf510d..2e900e878 100644 --- a/docs/sphinx/development.rst +++ b/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 diff --git a/docs/sphinx/development/contribution_guidelines.rst b/docs/sphinx/development/contribution_guidelines.rst index 559b2a381..fb80a0586 100644 --- a/docs/sphinx/development/contribution_guidelines.rst +++ b/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 `. + 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 `. 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 `. + 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. diff --git a/docs/sphinx/development/maintainer_notes.rst b/docs/sphinx/development/maintainer_notes.rst new file mode 100644 index 000000000..55b10d059 --- /dev/null +++ b/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 `_ 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 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 `. + +Update version number in `version header `_. + +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 `_, 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. diff --git a/docs/sphinx/development/version_control.rst b/docs/sphinx/development/version_control.rst deleted file mode 100644 index a47f43538..000000000 --- a/docs/sphinx/development/version_control.rst +++ /dev/null @@ -1,42 +0,0 @@ -Version control -*************** - -Branches -======== - -The following branches are used: - -* ``master`` -- Stable and ready-to-use branch for users. Should be tested on all supported platforms. Public releases are tagged from this branch. - -* ``develop`` -- Unstable branch for developers. May not be fully tested. From time to time it is considered ready and merged into the master branch. - -* ``feature/xxx`` -- Unstable feature branches for developers. Created for large work-in-progress features to allow the usual continuous integration and code review process without breaking the develop branch. Merged into develop when becomes ready. - -Releases -======== - -See `Releases `_ and :doc:`/development/changelog` pages for the list of releases and their detailed description. - -Releases are tagged from the master branch and named according to the `semantic versioning `_ 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 is always kept linear in the master and develop branches. - -The develop branch should be rebased on the master branch, and the feature branches and pull requests should be rebased on the develop branch. Not fast-forward merges into master and develop are not allowed. - -Pull requests -============= - -All pull-requests should be targeted on the develop branch. To be merged, a 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. - -A pull request should pass the :doc:`continuous integration ` checks and code review to be merged. diff --git a/docs/sphinx/development/workflow.rst b/docs/sphinx/development/workflow.rst new file mode 100644 index 000000000..74fdc6e7d --- /dev/null +++ b/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 `_ 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 `_ 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 ` 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.