| Gyorgy Szing | 0eb219f | 2022-11-25 11:55:31 +0100 | [diff] [blame^] | 1 | Version Control |
| 2 | =============== |
| 3 | |
| 4 | Version control is about tracking and managing changes to text files including source-code, scripts, configuration |
| 5 | files and documentation. |
| 6 | |
| 7 | The project uses the `Git version control system`_ and Gerrit as the code review and access restriction enforcement |
| 8 | solution. Although git is a distributed version control system the project uses a "centralized" approach. The main |
| 9 | repositories can be found at https://trustedfirmware.org, where two WEB UIs can be found: |
| 10 | |
| 11 | - a `cgit instance`_ allowing browse and clone the repositories |
| 12 | - and a `Gerrit instance`_ for contribution and code review purposes. |
| 13 | |
| 14 | Currently the project has a single repository hosting the source-code: |
| 15 | https://git.trustedfirmware.org/TS/trusted-services.git/ |
| 16 | |
| 17 | Branching Strategy |
| 18 | ------------------ |
| 19 | |
| 20 | The branching strategy is built around a "quality" based flow of changes. |
| 21 | |
| 22 | Each change starts targeting an "integration" branch either as a "standalone" change or as a topic. Changes landing on |
| 23 | integrations are expected to be "independent" (properly build and working without depending on other changes). |
| 24 | Validation efforts of the changes my have limited focus based on the expected effect of the change. This allows |
| 25 | balancing validation costs to pay during reviews. |
| 26 | |
| 27 | All change landing on the integration branch will get trough full validation. When passing all quality checks, the |
| 28 | change can be merged to a "main" branch. All changes on the main branch are expected to fulfill all quality requirements |
| 29 | and to pass full validation. |
| 30 | |
| 31 | The default name of the "integration" branch is ``integration`` and the default name of the "main" branch is ``main``. |
| 32 | For special purposes (e.g. long term support, hosting a special version, etc...) other branches acting as "integration" |
| 33 | and "main" can be defined. |
| 34 | |
| 35 | Sandbox branches |
| 36 | ---------------- |
| 37 | |
| 38 | For prototyping purposes the project allows using "sandbox" branches. Changes on these branches are free to lower |
| 39 | quality expectations as needed. Sandbox branches are to be created under ``sandbox/<username>/`` namespace |
| 40 | (e.g. ``sandbox/gyoszi01/static-init-prototype``). |
| 41 | |
| 42 | Topic branches |
| 43 | -------------- |
| 44 | |
| 45 | For large changes or changes expected to have a longer development time "topic" branches can be used. Topic branches are |
| 46 | to be created under the ``topics/<username>/<some name>`` namespace. If multiple developers are co-developing a feature |
| 47 | ``<username>`` is expect to be the lead developer. |
| 48 | |
| 49 | Review vs quality |
| 50 | ----------------- |
| 51 | |
| 52 | As discussed above all commits on the "integration" branch must properly build and work independent of other changes. |
| 53 | This may result in large commits, which would make code reviews difficult. To help the code review, large changes should |
| 54 | be split to small steps, each implementing a single logical step needed for the full change. To remove the conflict |
| 55 | between quality expectation requiring large and review requiring small commits, topic branches shall be used. Large |
| 56 | changes are to be split up to small steps and target a topic branch first. This way reviewers can check small changes, |
| 57 | and only the tip of the topic branch is to pass build and runtime tests. |
| 58 | |
| 59 | .. _`cgit instance`: https://git.trustedfirmware.org/ |
| 60 | .. _`Gerrit instance`: https://review.trustedfirmware.org/ |
| 61 | |
| 62 | ------------- |
| 63 | |
| 64 | .. _`Git version control system`: https://git-scm.com/ |
| 65 | |
| 66 | *Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.* |
| 67 | |
| 68 | SPDX-License-Identifier: BSD-3-Clause |