diff --git a/README.md b/README.md index b3b8a3c..dfe275c 100644 --- a/README.md +++ b/README.md @@ -3,4 +3,74 @@ # 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] +() + +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 apply, inside square brackets, to +top-level workflow names. + +| Prefix Letter | Function | Description | +| ------------- | -------- | ----------------- | +| R | Reusable | on: workflow_call | + +The above prefixes can combine into composites, but when doing so, preserve +alphabetic ordering for consistency/readability. + +e.g. +name: "[R] Python Build" + +### Gerrit Workflows + +Gerrit 'calling' workflows may have different trigger event types. Those +embedded behaviours mean a naming convention helps distinguish the different +types. + +They fall into four specific types: + +| Description | Filename in Repository | +| --------------------- | --------------------------------- | +| Gerrit (Verify) | gerrit-verify[-project-repo].yaml | +| Gerrit (Merge) | gerrit-merge[-project-repo].yaml | +| Gerrit (Generic) | gerrit-[project-repo].yaml | +| Gerrit (Word/Trigger) | gerrit-[word].yaml |