Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history 
Adapted repo management policy to readme
  • Loading branch information
@AFoletti
AFoletti authored Dec 3, 2024
1 parent 2e70dda commit 95482c2
Showing 1 changed file with 94 additions and 42 deletions.
136 changes: 94 additions & 42 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,70 +11,122 @@ The UML diagrams are typically folded into supporting documentation and are not

Such supporting documentation, e.g., documents in Office/PDF formats, is not maintained here.

## Branching and Tagging Conventions and Practices
The following expresses the conventions used for tagging and branching.
# Repository management policy
This section explains how this repository is governed.

### Tags
Every released standard as well as a version that is under consultation is tagged. The tagged version number will match the published version on the respective eCH website. Released and consultation versions are published on eCH and on BLW/OFAG/UFAG websites with supporting documentation.
## Membership and roles management

#### Tag prefixes
- All members of the Expert group outside of the FOAG receive the **“Outside collaborator”** organization membership. They have the “Read” role for all the eCH repositories.
Additionally, they may:

* consultation (eCH public consultation phase)
* release
- Waive this role for selected eCH repos where they are not directly involved (not part of the Expert group) and do not plan to get involved with.

#### Examples
- Waive this role completely if they do not plan to contribute on GitHub at all and consider this pure spam.

* consultation/v1 (initial major version)
* consultation/v2 (major version)
* consultation/v1.1 (minor version)
* consultation/v1.1.1 (patch version)
- Ask for the **Write** role in the repo(s) associated with their own Arbeitsgruppe(n) if they plan to contribute directly with Pull Requests (PR).

- Regular external developers are integrated into the organization as **“Outside Collaborator”** and receive by default the **Write** role on all eCH repositories.

* release/v1 (initial major version)
* release/v2 (major version)
* release/v1.1 (minor version)
* release/v1.1.1 (patch version)
Membership and roles are managed by the CCDT members.
Memberships and roles can be given or removed as soon as needed. CCDT makes a regular check of active users and adapts the accesses as needed.

## Issue management

### Branches
Issues MUST be opened using the available template (see picture). This ensures smooth coordination with the internal FOAG task board.

### Storing of referenced standards for validation purposes
An aspect of an in-progress branch is that it may contain a copy of a referenced standard, which may also be in an in-progress state, to allow validation locally.
Such a reference is updated when published and any local copy of the referenced standard removed in that tagged version.
![image](https://github.com/user-attachments/assets/e4a44cc8-0b9b-4e12-a9ea-f4c865a35f98)

#### Branch Naming
Issues need a meaningful title and a description clearly stating what the problem is or what needs to be changed/fixed.

#### Including a version in branch name
The versioning used in this repository matches the usage as defined by eCH.
Issues are triaged by the CCDT team, who also priotizes them and selects an assignee. They still remain a way for an open and honest discussion so everyone is invited to participate. The use of people mentions using“@username” is encouraged where an opinion is demanded.

In general the naming of branch versions corresponds to the convention of major/minor/patch as defined in common semantic versioning practice in identifying the type of change. A detailed article explaining this can be found here: https://semver.org/, roughly summarised here:
Issues are only closed by a member of the CCDT team (either in the issue itself or via the merge of a linked PR) or by the author of the issue itself.

a. Patch means that no breaking changes are present.
CCDT performs a review and triage of the issues, potentially closing stale ones, at least twice a year.

b. Minor means that an additive change has been recommended.
## Labels

c. Major means that either a breaking change is introduced or a major feature is introduced.
The CCDT members manage the available labels for the issues in the eCH repositories.

A breaking change is a mutation in datatype or element/attribute name, or a deletion.
The CCDT team is also responsible for issue labeling.

#### Naming prefixes
The following prefixes with matching semantic versioning are prescribed:
Each issue MUST have the following 2 labels:

* feature (major)
* improvement (minor)
* fix (patch)
- The ```JIRA``` label in order to ensure coordination with the FOAG internal task board

The prefixes are not intended to match the status options defined in eCH here (https://www.ech.ch/fr/standard-uebersicht / https://www.ech.ch/de/standard-uebersicht) as those names are reflected in the tag names.
- One of ```PATCH```, ```MINOR``` or ```MAJOR``` in order to identify the change scope

#### Branch Naming Examples
All issues MAY have

feature/v1/<someName>
- A label identifying the type of change request (```DOCUMENTATION```, ```ENHANCEMENT``` or ```BUG```)

improvement/v1/<someName>
improvement/v1.1/<someName>
improvement/v1.1.1/<someName>
- A label identifying the target release for issue resolution (e.g. ```1.3.0```)

fix/v1.1.1/<someName>
fix/v1.1.2/<someName>
- Additional labels, for example showcasing the urgency of the issue.

Where <someName> provides an immediate visual cue as to the nature of the change.
This labeling schema MAY be applied to Pull Requests (PR) too.

## Branch and release management

### Versioning

Version numbering follows the [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) guidelines with the following adaptations:

- Version numbering only considers Major, Minor, Patch and Pre-releases.

- A Patch can be, for example, typo fixes in the medatada or in the descriptions, which should not trigger an eCH review process.

- Pre-releases versions **MUST** be denoted by appending a hyphen (“-”) followed by an integer to the target main release number. E.g. **1.5.0-2** is the second pre-release for the 1.5.0 version.

### Branching

All of the eCH repositories adhere to the following general branch organization:

- A **“main”** branch, acting as the master
- The **“main”** branch is to be considered productive, valid and binding within the eCH context. **For this reason, there is no merge into the main branch if not related to an official new release.**
- The only exception of that is the README.md content, which is not considered part of the eCH standard and can thus be merged outside of the standard management cycle. Changes to the README.md MAY be committed directly into the main branch by the GRKDT team.


- **Release branches** named after the release version and prefixed with “Release-”(e.g. “Release-1.3.0”)
- Release branches coalesce all the changes needed for the future release of the new version.
- Release branches are opened by the CCDT team only.
- Release branches MAY be published on GitHub as pre-releases (see “Review and publishing process“ below).


- **Development branches** named with a “Dev-” prefix followed by free text (e.g. “Dev-AFoletti_patch1_n”)
- The Development branches fix specific issues or implement specific enhancements and are usually linked to an Issue.

### Review and publishing process

The review and publishing process of the code in this repository has 4 main steps.

1. Work is done in a Development branch. Once finished, the author opens a Pull Request (PR). Pull requests from **Development** branches into **Release** branches can be opened by every member with Write permissions.

![image](https://github.com/user-attachments/assets/75367751-ebfd-4f23-b050-f0f6772cc4f0)


2. Team CCDT reviews the PR and merges the code into the appropriate Release branch. **Only the CCDT Team can merge those PRs.**

3. Once a release is considered complete, the CCDT Team MUST publish a pre-release from this branch. **Exception** to that is a patch version, which does not need an eCH review process. A patch release can thus be merged into main and published as a new version by the CCDT alone.

Pre-releases are tagged according to the versioning rules (see above) and given a meaningful name.
![image](https://github.com/user-attachments/assets/8c030ce4-983a-4806-9942-62aa4873cb66)

They MUST be set as pre-release before publishing

![image](https://github.com/user-attachments/assets/49caace2-2d72-4351-9330-644dcc85c542)

The pre-release then follow the eCH validation process according to the change scope (minor, major). The code and documentation of the pre-release is sent to the relevant stakeholders that have the opportunity to ask for modifications or accept the new release.
See [eCH-0003 - Leitfaden zur Genehmigung von Anträgen](https://ech.ch/de/ech/ech-0003) and [eCH-0150 - Change und Release Management von eCH-Standards](https://ech.ch/de/ech/ech-0150).

4. Once the eCH validation process is done and the release is accepted, the CCDT merges the release branch into main.

![image](https://github.com/user-attachments/assets/3f5f0ead-a3a9-42bf-96cd-52b1872df2f9)

5. The CCDT then publishes a new official release tagged with the appropriate release number.

![image](https://github.com/user-attachments/assets/5a0e1a7f-f1fa-4bd6-850f-cf66707f0af3)

## Contact

For general questions and request write access to this repo, please send a mail to kompetenzzentrumdigitaletransformation@blw.admin.ch

0 comments on commit 95482c2

Please sign in to comment.