Skip to content

Commit

Permalink
Chore: Add naming conventions to documentation
Browse files Browse the repository at this point in the history
Signed-off-by: Matthew Watkins <[email protected]>
  • Loading branch information
ModeSevenIndustrialSolutions committed Oct 24, 2024
1 parent cc59fef commit ebe5a54
Showing 1 changed file with 72 additions and 1 deletion.
73 changes: 72 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,75 @@

# releng-reusable-workflows

Reusuable workflows developed by LF Release Engineering
GitHub actions/workflows developed by the Linux Foundation Release Engineering
team.

## Naming Conventions

### File and Directory Names

## Location, Naming and Labelling of Actions

You can find actions in folders under the directory:

.github/actions/

These can be of three basic types, as described in the [GitHub documentation]
(<https://docs.github.com/en/actions/sharing-automations/creating-actions/about-custom-actions>)

The table below describes the labelling and locations:

| Description | Directory Suffix |
| ----------- | ---------------- |
| Composite | -action |
| Javascript | -javascript |
| Docker | -docker |

Documentation takes the form of a README.md or README.rst file hosted alongside
the YAML file in one of the directory locations described above.

## Naming of Workflow YAML files

The GitHub actions and workflows in this repository conform to the
following naming conventions:

| Filename Prefix | Functional Description |
| --------------- | --------------------------------------------- |
| call- | Top-level parent workflows that call others |
| reuse- | Reusable workflows implementing workflow_call |

## Name/Labelling within Workflows

Labelling must avoid consuming excessive space in the web/portal sidebar.
With this in mind, some standard abbreviations help minimise text overflow.

### Workflow Naming Prefixes

The table below lists prefixes that applied, inside square brackets, to
top-level workflow names.

| Prefix Letter | Function | Description |
| ------------- | ------------ | --------------------- |
| M | Manual | on: workflow_dispatch |
| R | Reusable | on: workflow_call |
| V | Verification | Verification/Checks |

The above prefixes can combine into composites, but when doing so, preserve
alphabetic ordering for consistency/readability.

e.g.
name: "[MV] Check Action SHA Pinning"

### Gerrit Workflows

Gerrit 'calling' workflows may have different trigger event types. Those
embedded behaviours mean a naming prefix helps distinguish the different
types.

They fall into three specific types:

| Workflow Prefix | Description | Filename in Repository |
| --------------- | ---------------- | ---------------------- |
| [GV] | Gerrit (Verify) | gerrit-verify.yaml |
| [GM] | Gerrit (Merge) | gerrit-merge.yaml |
| [G] | Gerrit (Generic) | [either of the above] |

0 comments on commit ebe5a54

Please sign in to comment.