Issue implementation

Overview

  • docs-as-code

  • Word

Introduction

Projects at ASAM use trunk-based repositories.

A trunk-based repository is a repository that has a single central branch (the "trunk"). This trunk contains the official and reviewed state of a project.
Users are not allowed to commit and push changes to this specific branch directly. Instead, all changes on the repository’s content are made in child branches. These can either be branched off of the trunk or from another branch. Once ready, a branch is merged back into its parent branch (which may be the trunk or another feature branch).

The benefit of this approach is that each repository’s trunk contains the latest official state or version. Mistakes and unfinished changes to parts of it only have an impact on the branch where they happen.

Never work on the trunk directly — always work in separate branches!

The trunk

The central branch ("trunk") can only be merged to by the ASAM office, the Project Lead, or the project’s Change Control Board (CCB). Tags are used to identify fixed states of the repository, including official releases and other versions where the project deems it necessary. Version-based tags use semantic versioning.

Changes MUST be added through branches created from the trunk or another branch.
These branches SHOULD be short-lived (<2 weeks) and regularly merged back.
These branches MAY be squashed and MUST be merged via fast-forward merge (enabled by default).

Implementing issues

  1. Once an issue can be implemented, the issue’s assignee creates a branch with an associated Merge or Pull Request from the issue.

    • Each branch must have a parent issue and each issue may have zero or one child branches.

  2. Begin submitting work via commits to the branch.

    1. Involved project participants review and comment changes through the associated Pull/Merge Request. These comments work identically to those described in "discuss issues".

  3. Review implementation progress of issue with other project participants in Subgroup or project meetings. Discussions and their results are documented in the Pull/Merge Request

  4. Once the group agrees that the feature is complete, the issue state transitions to .

    1. If the Merge/Pull Request is set to "Draft:", remove the draft flag from the Merge/Pull Request name

      Tips

      • If a branch cannot be short-lived, rebase frequently to incorporate upstream changes.

      • Create branches directly from the issue to ensure the branch is linked to the issue.

        • This also provides the option to set up the related Merge/Pull Request right away. This way, the Merge/Pull Request (and its branch) are already accessible through the parent issue.

        • Adding "DRAFT: " in front of a Merge/Pull Request’s name marks it as not ready for merge and disables the "Merge" button. This way, the Merge/Pull Request (and its branch) cannot be concluded by accident.
We are continually working on growing the project guide. This section is still being prepared. Please reach out to the ASAM office if you have any questions.