Skip to content

Commit 516c7e2

Browse files
gavvgavv
committed
Update sphinx documentation
1 parent d7ad6d1 commit 516c7e2

File tree

6 files changed

+201
-48
lines changed

6 files changed

+201
-48
lines changed

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ See details here:
5757

5858
* [GitHub releases](https://github.com/roc-streaming/roc-toolkit/releases)
5959
* [Changelog](https://roc-streaming.org/toolkit/docs/development/changelog.html)
60-
* [Version control](https://roc-streaming.org/toolkit/docs/development/version_control.html)
60+
* [Development workflow](https://roc-streaming.org/toolkit/docs/development/workflow.html)
6161

6262
Platforms
6363
---------

‎docs/sphinx/development.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,5 +8,6 @@ Development
88
development/roadmap
99
development/contribution_guidelines
1010
development/coding_guidelines
11-
development/version_control
11+
development/workflow
12+
development/maintainer_notes
1213
development/continuous_integration

‎docs/sphinx/development/contribution_guidelines.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ How you can help
1818

1919
* **Writing**
2020

21-
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>`.
21+
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>`.
2222

2323
Becoming a contributor
2424
======================
@@ -58,8 +58,8 @@ The guide bellow will help you to prepare your first patch.
5858

5959
* **Step 5: Create pull request!**
6060

61-
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>`.
61+
See :doc:`/development/workflow` page for rules of pull request creation and its life-cycle.
6262

63-
Before submitting PR, don't forget to run code formatting, as described in coding guidelines.
63+
Please remember that pull requests should be always rebased on ``develop`` branch and should be targeted to it!
6464

65-
Please ensure that all CI checks pass on your PR and fix them if needed.
65+
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‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
Maintainer notes
2+
****************
3+
4+
.. contents:: Table of contents:
5+
:local:
6+
:depth: 1
7+
8+
Merging pull request
9+
====================
10+
11+
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:
12+
13+
- Rebases PR on up-to-date develop branch.
14+
- If requested, squashes all commits into one.
15+
- 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.
16+
- Force-pushes updated commits to PR's branch.
17+
- Asks GitHub to merge PR.
18+
19+
You should choose whether to merge by rebasing or squashing.
20+
21+
Merge PR by rebasing:
22+
23+
.. code::
24+
25+
scripts/pr.py merge --rebase 123
26+
27+
Merge PR by rebasing and squashing all commits into one:
28+
29+
.. code::
30+
31+
scripts/pr.py merge --squash 123
32+
33+
If PR description doesn't have a link to issue, the script will complain and fail. You can manually specify it:
34+
35+
.. code::
36+
37+
scripts/pr.py merge --rebase 123 --issue 456
38+
39+
The script will use given issue for commits and also will add it to PR description.
40+
41+
Show PR info before merging it:
42+
43+
.. code::
44+
45+
scripts/pr.py show 123
46+
47+
Link PR commits to issue and force-push to PR's branch, but don't merge PR:
48+
49+
.. code::
50+
51+
scripts/pr.py link 123
52+
53+
Revert that:
54+
55+
.. code::
56+
57+
scripts/pr.py unlink 123
58+
59+
For the full list of available options, see:
60+
61+
.. code::
62+
63+
scripts/pr.py [command] --help
64+
65+
Rebasing develop on master
66+
==========================
67+
68+
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.
69+
70+
Update branches:
71+
72+
.. code::
73+
74+
git switch master && git pull origin master
75+
git switch develop && git pull origin develop
76+
77+
Rebase ``develop`` on ``master``:
78+
79+
.. code::
80+
81+
scripts/rebase.sh master
82+
83+
Push to your fork:
84+
85+
.. code::
86+
87+
git push -f <your fork> develop
88+
89+
When CI on your fork passes, push to origin:
90+
91+
.. code::
92+
93+
git push -f origin develop
94+
95+
Updating master to develop
96+
==========================
97+
98+
Before doing this, first ensure that branches are up-to-date and ``develop`` is rebased on ``master``.
99+
100+
Then fast-forward ``master`` to ``develop``:
101+
102+
.. code::
103+
104+
git switch master
105+
git merge --ff-only develop
106+
107+
Creating release
108+
================
109+
110+
Rename ``next`` milestone to ``v1.2.3`` and close it. Create new ``next`` milestone.
111+
112+
Add new release to :doc:`changelog page </development/changelog>`.
113+
114+
Update version number in `version header <https://github.com/roc-streaming/roc-toolkit/blob/develop/src/public_api/include/roc/version.h>`_.
115+
116+
Update specs for debian and rpm packages:
117+
118+
.. code::
119+
120+
scripts/update_packages.py
121+
122+
Update authors page:
123+
124+
.. code::
125+
126+
scripts/update_authors.sh
127+
128+
Create and push tag:
129+
130+
.. code::
131+
132+
git tag v1.2.3
133+
git push origin v1.2.3
134+
135+
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.
136+
137+
Post announcement to matrix and, in case of big releases, to the mailing list.

‎docs/sphinx/development/version_control.rst‎

Lines changed: 0 additions & 42 deletions
This file was deleted.

‎docs/sphinx/development/workflow.rst‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
Development workflow
2+
********************
3+
4+
.. contents:: Table of contents:
5+
:local:
6+
:depth: 1
7+
8+
Branches
9+
========
10+
11+
The following branches are used:
12+
13+
* ``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.
14+
15+
* ``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.
16+
17+
Releases
18+
========
19+
20+
See `Releases <https://github.com/roc-streaming/roc-toolkit/releases>`_ and :doc:`/development/changelog` pages for the list of releases and their detailed description.
21+
22+
Releases are **tagged from master** branch and named according to the `semantic versioning <https://semver.org/>`_ rules:
23+
24+
* patch version Z (x.y.Z) is incremented when introducing backwards-compatible bug fixes;
25+
* minor version Y (x.Y.z) is incremented when introducing backwards-compatible features;
26+
* major version X (X.y.z) is incremented when introducing backwards-incompatible changes.
27+
28+
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.
29+
30+
History
31+
=======
32+
33+
History in ``master`` and ``develop`` branches is **kept linear**. Only fast-forward merges and rebases are used.
34+
35+
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.
36+
37+
Pull requests
38+
=============
39+
40+
All pull-requests should be **targeted to develop** branch. Pull request should be rebased on the latest commit from that branch.
41+
42+
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.
43+
44+
To be merged, a pull request should pass the :doc:`continuous integration </development/continuous_integration>` checks and code review.
45+
46+
Review cycle
47+
============
48+
49+
The following labels are used during code review to indicate pull request state:
50+
51+
- ``work in progress`` -- author is doing changes and maintainer should not do review
52+
- ``ready for review`` -- author have finished doing changes and requests review from maintaner
53+
- ``review in progress`` -- maintainer started doing review; used when review can take long time, e.g. a few days
54+
- ``needs revision`` -- maintainer finished review and requested updates or clarifications from author
55+
- ``needs rebase`` -- automatically added when CI detects that there are unresolved conflicts; author should rebase PR on fresh develop branch
56+
57+
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.

0 commit comments

Comments
 (0)