diff options
author | Christoph Wurst <christoph@winzerhof-wurst.at> | 2022-11-02 11:41:05 +0300 |
---|---|---|
committer | Christoph Wurst <christoph@winzerhof-wurst.at> | 2022-11-02 12:18:15 +0300 |
commit | 8ff26fba58ddce2e0c54e8cb3f85d2a7518a65cd (patch) | |
tree | 7d6ac3203865559a503fe8818a0e34b726e92961 | |
parent | e8950a8055f03e463ad000c25980d3946615faa1 (diff) |
Document development process and backports
Signed-off-by: Christoph Wurst <christoph@winzerhof-wurst.at>
-rw-r--r-- | developer_manual/getting_started/development_process.rst | 69 | ||||
-rw-r--r-- | developer_manual/getting_started/index.rst | 1 |
2 files changed, 70 insertions, 0 deletions
diff --git a/developer_manual/getting_started/development_process.rst b/developer_manual/getting_started/development_process.rst new file mode 100644 index 000000000..c76d74ef0 --- /dev/null +++ b/developer_manual/getting_started/development_process.rst @@ -0,0 +1,69 @@ +=================== +Development process +=================== + +This page gives an overview of how Nextcloud code is developed. + +Source Code Version Control +--------------------------- + +Nextcloud uses `git <https://git-scm.com/>`_ to manage revisions of the code. Software components have their own repositories. + +Branch Names +^^^^^^^^^^^^ + +Default branches of Nextcloud and its app repositories are named ``main`` or ``master``. Additionally, there are *stable branches* whenever a major version of Nextcloud is released. Those are named ``stableX``, where X refers to the version. For Nextcloud 25, for example, the stable branch is named ``stable25``. + +Target Branches for Contributions +--------------------------------- + +Any changes made to the source code go into the default branch of a repository through a `pull request <https://docs.github.com/en/pull-requests>`_. + +.. code-block:: bash + + # Switch to the default branch and update it + git checkout main + git pull origin/main + + # Create the new feature branch + git checkout -b feature/foo-bar + + # Add and commit the changes + git add file1 file2 + git commit --signoff -m 'Add foo bar' + + # Push the new commit to the remote repository and open a pull request + git push origin feature/foo-bar + +Bugfixes +^^^^^^^^ + +If a contribution fixes a bug that also affects older Nextcloud or app releases, it may qualify for a *backport*. Backporting a fix means applying the change on an older version of the code. Git calls this operation *cherry picking*. + +Automatic Backport +****************** + +In many cases the cherry pick results in a clean apply of the patch and git is able to resolve any small conflicts. In those cases it's easiest to let the `backport bot <https://github.com/nextcloud/backportbot>`_ do the backport. + +See the `bot usage <https://github.com/nextcloud/backportbot#usage>`_ for its commands. + +Manual Backport +*************** + +More complex changes may require the developer to do the backport manually. This can be done as follows: + +.. code-block:: bash + + # Switch to the target branch and update it + git checkout stable25 + git pull origin/stable25 + + # Create the new backport branch + git checkout -b fix/foo-stable25 + + # Cherry pick the change from the commit sha1 of the change against the default branch + # This might cause conflicts. Resolve them. + git cherry-pick abc123 + + # Push the cherry pick commit to the remote repository and open a pull request + git push origin fix/foo-stable25 diff --git a/developer_manual/getting_started/index.rst b/developer_manual/getting_started/index.rst index ab7e2f242..3eeab21ec 100644 --- a/developer_manual/getting_started/index.rst +++ b/developer_manual/getting_started/index.rst @@ -5,6 +5,7 @@ Getting started .. toctree:: :maxdepth: 2 + development_process devenv codingguidelines debugging |