From 93e0474499c78e9b3156f0647790bcba44903d82 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dirk=20M=C3=BCller?= Date: Thu, 28 Sep 2023 17:46:37 +0200 Subject: [PATCH 1/4] Update README --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b064d9e..bb766cf 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ -# OpenELA Project Documentation -Documentation for the OpenELA Project +# OpenELA Governance Documentation -* [Repository Structure](repository_structure.md) \ No newline at end of file +Governance documentation for the OpenELA Project: + +* [Contributors Guidelines](contributors_guidelines.md) +* [Repository Structure](repository_structure.md) From a9332d0bcf44d452f3f79699a0fddd1fda1612b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dirk=20M=C3=BCller?= Date: Thu, 28 Sep 2023 18:04:05 +0200 Subject: [PATCH 2/4] Add markdown linter --- .github/workflows/markdown-lint.yaml | 14 ++++++++++++++ .mdl_style.rb | 2 ++ .mdlrc | 1 + 3 files changed, 17 insertions(+) create mode 100644 .github/workflows/markdown-lint.yaml create mode 100644 .mdl_style.rb create mode 100644 .mdlrc diff --git a/.github/workflows/markdown-lint.yaml b/.github/workflows/markdown-lint.yaml new file mode 100644 index 0000000..fa99670 --- /dev/null +++ b/.github/workflows/markdown-lint.yaml @@ -0,0 +1,14 @@ +name: markdownlint + +on: [push, pull_request] + +jobs: + lint-markdown: + runs-on: ubuntu-latest + steps: + - name: Check out code + uses: actions/checkout@v2 + - name: Run Markdown Lint + uses: actionshub/markdownlint@main + - name: Run Link check + uses: gaurav-nelson/github-action-markdown-link-check@v1 diff --git a/.mdl_style.rb b/.mdl_style.rb new file mode 100644 index 0000000..4a32dcf --- /dev/null +++ b/.mdl_style.rb @@ -0,0 +1,2 @@ +all +rule 'MD026', :punctuation => '.,;:!' diff --git a/.mdlrc b/.mdlrc new file mode 100644 index 0000000..1f82ca2 --- /dev/null +++ b/.mdlrc @@ -0,0 +1 @@ +style '.mdl_style.rb' From e33d564ebf21b3230ce6b7bda07faa8858cee242 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dirk=20M=C3=BCller?= Date: Thu, 28 Sep 2023 18:09:22 +0200 Subject: [PATCH 3/4] Adjust for linting --- contributors_guidelines.md | 129 +++++++++++++++++++++++++++---------- repository_structure.md | 128 ++++++++++++++++++++++++------------ 2 files changed, 184 insertions(+), 73 deletions(-) diff --git a/contributors_guidelines.md b/contributors_guidelines.md index df53ca4..99905ae 100644 --- a/contributors_guidelines.md +++ b/contributors_guidelines.md @@ -1,71 +1,134 @@ -## Contribution Guidelines +# OpenELA Contribution Guidelines -### Scope +## Scope -OpenELA welcomes contributions from the community seeking to improve the experience of users on Enterprise Linux. Contributions to OpenELA must adhere to the following guidelines. +OpenELA welcomes contributions from the community seeking to improve the +experience of users on Enterprise Linux. Contributions to OpenELA must adhere +to the following guidelines. -The goal of OpenELA is to provide continuity for Enterprise Linux downstream distributions by providing a secure, transparent, and reliable Enterprise Linux (EL) source that is globally available to anyone as a buildable base. OpenELA allows distributions to create and maintain downstream derivatives of EL. +The goal of OpenELA is to provide continuity for Enterprise Linux downstream +distributions by providing a secure, transparent, and reliable Enterprise Linux +(EL) source that is globally available to anyone as a buildable base. OpenELA +allows distributions to create and maintain downstream derivatives of EL. -### What Can be Contributed to OpenELA? +## What Can be Contributed to OpenELA? -Most contributions should not go directly into OpenELA. Contributions are governed by similar rules to other Linux stable projects, i.e. contributions to OpenELA must have antecedents in the upstream for those distributions. +Most contributions should not go directly into OpenELA. Contributions are +governed by similar rules to other Linux stable projects, i.e. contributions to +OpenELA must have antecedents in the upstream for those distributions. -#### What is a “Patch”? +### What is a “Patch”? -Patches are fixes, changes, and enhancements specific to a single project or package. +Patches are fixes, changes, and enhancements specific to a single project or +package. -“Bug Fix Patches” are Patches that are present in the upstream repository or the upstream distribution repository and improve stability, robustness or security of the already present features. They are backward binary compatible and do not break previously documented behavior or features. +“Bug Fix Patches” are Patches that are present in the upstream repository or +the upstream distribution repository and improve stability, robustness or +security of the already present features. They are backward binary compatible +and do not break previously documented behavior or features. -#### Contribute Upstream First! +### Contribute Upstream First -Before Patches are considered for OpenELA, Developers are encouraged to contribute patches to upstream. If you’re having trouble finding the upstream for a particular project, check the Source line in the SRPM. We don’t want OpenELA to become a repository for orphaned patches, and it’s very important to encourage developers to contribute their efforts to the upstream projects. +Before Patches are considered for OpenELA, Developers are encouraged to +contribute patches to upstream. If you’re having trouble finding the upstream +for a particular project, check the Source line in the SRPM. We don’t want +OpenELA to become a repository for orphaned patches, and it’s very important to +encourage developers to contribute their efforts to the upstream projects. -In some cases, you may need to contribute to both the project upstream (i.e. github.com/upstream/project) and also to the upstream distribution version of that package prior to getting that change into OpenELA. +In some cases, you may need to contribute to both the project upstream (i.e. +github.com/upstream/project) and also to the upstream distribution version of +that package prior to getting that change into OpenELA. -There may be specific exceptions defined to the “Upstream First” policy per the Technical Steering Committee, which will be linked here if and when defined. +There may be specific exceptions defined to the “Upstream First” policy per the +Technical Steering Committee, which will be linked here if and when defined. ### The Bug-for-Bug Compatibility Standard -The “bug-for-bug” compatibility provides a strict metric for maintaining compatibility with Enterprise Linux: while there are often multiple possible fixes to a particular bug, maintaining bug-for-bug compatibility shortcuts those technical discussions about “which fix is best” by requiring the -main version to be “equally broken” with upstream EL. Maintaining bug-for-bug compatibility also provides an avenue for distributions downstream of OpenELA to provide value. +The “bug-for-bug” compatibility provides a strict metric for maintaining +compatibility with Enterprise Linux: while there are often multiple possible +fixes to a particular bug, maintaining bug-for-bug compatibility shortcuts +those technical discussions about “which fix is best” by requiring the -main +version to be “equally broken” with upstream EL. Maintaining bug-for-bug +compatibility also provides an avenue for distributions downstream of OpenELA +to provide value. -### Sign-off your Submissions +## Sign-off your Submissions -Changes should be signed off using the DCO ([Developer’s Certificate of Origin](https://developercertificate.org/), as defined in the [Linux Kernel documentation](https://www.kernel.org/doc/Documentation/process/submitting-patches.rst)). +Changes should be signed off using the DCO ([Developer’s Certificate of +Origin](https://developercertificate.org/), as defined in the [Linux Kernel +documentation](https://www.kernel.org/doc/Documentation/process/submitting-patches.rst)). -### Contribute under the Project’s License +## Contribute under the Project’s License -Any changes to projects must be submitted under the project’s existing license and comply with the license of the project being changed. OpenELA projects shall not deviate from or modify the license from the upstream program’s license terms. +Any changes to projects must be submitted under the project’s existing license +and comply with the license of the project being changed. OpenELA projects +shall not deviate from or modify the license from the upstream program’s +license terms. -Any additional content of new packages, such as specfiles, are licensed under the same license terms of the project being distributed unless explicitly defined otherwise and with exceptions approved by the Technical Steering Committee. Contributions to the contrib branches of the openela-main organization shall keep the original license of additional content. +Any additional content of new packages, such as specfiles, are licensed under +the same license terms of the project being distributed unless explicitly +defined otherwise and with exceptions approved by the Technical Steering +Committee. Contributions to the contrib branches of the openela-main +organization shall keep the original license of additional content. -New projects which exist only in OpenELA shall have a toplevel LICENSE or COPYING file which explicitly define the license for the project, and that license must be an OSI-approved Open Source License. Licenses shall have a SPDX license identifier assigned and shall be Open Source according to the Open Source Definition [as maintained by the Open Source Initiative](https://opensource.org/osd/). +New projects which exist only in OpenELA shall have a toplevel LICENSE or +COPYING file which explicitly define the license for the project, and that +license must be an OSI-approved Open Source License. Licenses shall have a SPDX +license identifier assigned and shall be Open Source according to the Open +Source Definition [as maintained by the Open Source +Initiative](https://opensource.org/osd/). -New and unique contributions to OpenELA which are not part of an existing open source project may have additional requirements which have yet to be defined. +New and unique contributions to OpenELA which are not part of an existing open +source project may have additional requirements which have yet to be defined. ## Contributing to openela-main -Contributions are welcome to openela-main repositories, however those repositories must maintain __strict bug-for-bug compatibility__ with EL. +Contributions are welcome to openela-main repositories, however those +repositories must maintain __strict bug-for-bug compatibility__ with EL. -Bug Fix Patches and other patches which are not bug-for-bug compatible with EL are not permitted in the main repositories, and must be submitted to -contrib repos as described below. +Bug Fix Patches and other patches which are not bug-for-bug compatible with EL +are not permitted in the main repositories, and must be submitted to -contrib +repos as described below. -Write access to the primary OpenELA branches is restricted to members of the Technical Steering Committee, who are responsible for ensuring that those commits respect the bug-for-bug compatibility requirements. +Write access to the primary OpenELA branches is restricted to members of the +Technical Steering Committee, who are responsible for ensuring that those +commits respect the bug-for-bug compatibility requirements. ## Contributing to openela-contrib -Maintaining patches in a contrib repo is a long-term commitment that will require maintenance any time the ‘base’ or upstream package changes. Therefore projects in the ‘openela-contrib’ repository will be created on demand and when a maintainer is stepping up to take the burden on maintaining the contributed package. +Maintaining patches in a contrib repo is a long-term commitment that will +require maintenance any time the ‘base’ or upstream package changes. Therefore +projects in the ‘openela-contrib’ repository will be created on demand and when +a maintainer is stepping up to take the burden on maintaining the contributed +package. -### Contributing New Packages into -contrib repos +## Contributing New Packages into -contrib repos -Contributions of new packages to OpenELA are welcome in the openela-contrib organization. These are packages which are not part of Upstream EL but which add value to the OpenEL Ecosystem. +Contributions of new packages to OpenELA are welcome in the openela-contrib +organization. These are packages which are not part of Upstream EL but which +add value to the OpenEL Ecosystem. -Branches within the openela-contrib repo should retain the ‘contrib’ tag in their branch names, to ensure that it is clear that these branches are not bug-for-bug compatible with EL. +Branches within the openela-contrib repo should retain the ‘contrib’ tag in +their branch names, to ensure that it is clear that these branches are not +bug-for-bug compatible with EL. -### Contributing Bug Fix Patches into -contrib repos +## Contributing Bug Fix Patches into -contrib repos -### Document Governance -This document is owned and updated by the Technical Steering Committee. Please supply all suggested modifications for consideration by the Technical Steering Committee through the usual github constructs. +Patches and Bug Fix Patches are welcome in the openela-contrib repositories. +This may require duplicating a repository between openela-main (which is +bug-for-bug compatible) and the openela-contrib repositories (which can be +patched). Branches should include the tag ‘-contrib’ to allow for being able +to `git clone` both the main and -contrib repositories into the same local git +repo. -Patches and Bug Fix Patches are welcome in the openela-contrib repositories. This may require duplicating a repository between openela-main (which is bug-for-bug compatible) and the openela-contrib repositories (which can be patched). Branches should include the tag ‘-contrib’ to allow for being able to `git clone` both the main and -contrib repositories into the same local git repo. +Patches which are accepted to the -contrib branches should meet the “Bug Fix +Patches” compatibility. The Technical Governance board can further define +additional exceptions. Patches for -contrib branches must be present in the +upstream project repository. Patches which are not applicable to or not +accepted by upstream will require review by the Technical Steering Committee. -Patches which are accepted to the -contrib branches should meet the “Bug Fix Patches” compatibility. The Technical Governance board can further define additional exceptions. Patches for -contrib branches must be present in the upstream project repository. Patches which are not applicable to or not accepted by upstream will require review by the Technical Steering Committee. +## Document Governance +This document is owned and updated by the Technical Steering Committee. Please +supply all suggested modifications for consideration by the Technical Steering +Committee through the usual github constructs. diff --git a/repository_structure.md b/repository_structure.md index 8b05dbd..b045ce0 100644 --- a/repository_structure.md +++ b/repository_structure.md @@ -1,111 +1,159 @@ -## OpenELA Repository Structure +# OpenELA Repository Structure -OpenELA will maintain publicly accessible git repositories of package sources necessary to create an Enterprise Linux compatible distribution. +OpenELA will maintain publicly accessible git repositories of package sources +necessary to create an Enterprise Linux compatible distribution. -One of the goals of the OpenELA project is to build and maintain maximum technology independence in our public resources. Furthermore, in order to maintain compatibility and independence, OpenELA repositories will rely on DistGit instead of git-lfs for binary storage, and will organize these into a small set of “organizations” with flat structure.This will make it possible for the project to be hosted on any git backend infrastructure. +One of the goals of the OpenELA project is to build and maintain maximum +technology independence in our public resources. Furthermore, in order to +maintain compatibility and independence, OpenELA repositories will rely on +DistGit instead of git-lfs for binary storage, and will organize these into a +small set of “organizations” with flat structure.This will make it possible for +the project to be hosted on any git backend infrastructure. +## Package Repository Structure -### Package Repository Structure +### DistGit -#### DistGit +All operating system sources will be broken down into separate DistGit +repositories. A DistGit repo is a Git repository which includes text files and +sources and referrals to the binary components so they are not included in the +Git repository directly. -All operating system sources will be broken down into separate DistGit repositories. A DistGit repo is a Git repository which includes text files and sources and referrals to the binary components so they are not included in the Git repository directly. +DistGit is preferred to git-lfs as it does not require special support from the +git “forge”, nor is it subject to the kinds of storage and bandwidth +limitations that come along with git-lfs support on some platforms. -DistGit is preferred to git-lfs as it does not require special support from the git “forge”, nor is it subject to the kinds of storage and bandwidth limitations that come along with git-lfs support on some platforms. +The source packages for OpenELA will exist in a multi-repository structure, +where every repository represents a single package and binary files are +referred to via a link (DistGit). Each package Git repository will contain a +structure which can be used to build directly from and/or create SRPMs from. -The source packages for OpenELA will exist in a multi-repository structure, where every repository represents a single package and binary files are referred to via a link (DistGit). Each package Git repository will contain a structure which can be used to build directly from and/or create SRPMs from. +### Branch Naming for Repositories -#### Branch Naming for Repositories - -Branches will be used to identify the target for each source package. For example: +Branches will be used to identify the target for each source package. For +example: In openela-main organisation, these branch names are specified: * **Base**: `el-9.0`, `el-9.1` * **Modulemd**: `el-9.1-modulemd-$STREAM` - * This contains _only_ the module document (modulemd). This is because a module might be a component, but also just a standalone module with other components. The modulemd is also relatively stable compared to SRPMs. + * This contains _only_ the module document (modulemd). This is because a + module might be a component, but also just a standalone module with other + components. The modulemd is also relatively stable compared to SRPMs. * **Module component**: `el-9.1-module-$STREAM` - * Contains the SRPM content like **Base**. Used for components of modules and separate from base due to each module stream having the ability to have a different version. - + * Contains the SRPM content like **Base**. Used for components of modules and + separate from base due to each module stream having the ability to have a + different version. In openela-contrib, these branch names are specified: * **Base**: `el-9.0-contrib`, `el-9.1-contrib` * **Modulemd**: `el-9.1-modulemd-$STREAM-contrib` - * This contains _only_ the module document (modulemd). This is because a module might be a component, but also just a standalone module with other components. The modulemd is also relatively stable compared to SRPMs + * This contains _only_ the module document (modulemd). This is because a + module might be a component, but also just a standalone module with other + components. The modulemd is also relatively stable compared to SRPMs * **Module component**: `el-9.1-module-$STREAM` - * Contains the SRPM content like “Base”. Used for components of modules and separate from base due to each module stream having the ability to have a different version. + * Contains the SRPM content like “Base”. Used for components of modules and + separate from base due to each module stream having the ability to have a + different version. **Note:** *refer to the Contributor Policy for specifics on contributions.* -#### Toplevel GitHub Organizations +### Toplevel GitHub Organizations -Within GitHub, OpenELA will be organized into the following top-level organizations: +Within GitHub, OpenELA will be organized into the following top-level +organizations: -* – The main repo for all root level tooling and repos (e.g. website, helper tools, and projects) -* – A series of DistGit repos for hosting the base OS packages -* – A series of DistGit repos for hosting community maintained patches and packages. +* – The main repo for all root level tooling and + repos (e.g. website, helper tools, and projects) +* – A series of DistGit repos for hosting + the base OS packages +* – A series of DistGit repos for hosting + community maintained patches and packages. -### Main Project Repo: +## Main Project Repo: -This organisation contains all repositories other than the DistGit (operating system sources). For example, this includes: +This organisation contains all repositories other than the DistGit (operating +system sources). For example, this includes: * Website sources -* Tooling for use with DistGit: This tooling should be able to pull and push from the Lookaside cache as needed as well tools for doing local builds via Mock. A similar tool exists for Fedora called “fedpkg”. +* Tooling for use with DistGit: This tooling should be able to pull and push + from the Lookaside cache as needed as well tools for doing local builds via + Mock. A similar tool exists for Fedora called “fedpkg”. * ELProfile: A compatibility tool for testing/validating EL derivatives * Documentation -### Base OS Repo: +## Base OS Repo: -The OpenELA-main is the primary organisation for all Enterprise Linux sources. It will serve as the location for the 1:1 compatible pristine unbranded sources. +The OpenELA-main is the primary organisation for all Enterprise Linux sources. +It will serve as the location for the 1:1 compatible pristine unbranded +sources. **DistGit Structure for the OpenELA Main Repo:** * `SPECS`: location of the RPM spec file * `SOURCES`: location of all non-binary source files -* `PATCHES`: Any “open patch” patches or changes that we apply to the upstream sources (e.g. debranding) -* `RPM header`: this is a binary header from the original SRPM that can be used to validate upstream signature and checksums of files (note, this might be put into the Lookaside cache depending on size) +* `PATCHES`: Any “open patch” patches or changes that we apply to the upstream + sources (e.g. debranding) +* `RPM header`: this is a binary header from the original SRPM that can be used + to validate upstream signature and checksums of files (note, this might be + put into the Lookaside cache depending on size) * `checksums`: hash and file name/path for the object store Lookaside cache * `maintainers`: list of package maintainers (only for contrib packages) -* `.gitignore`: Any binary files that exist in a Lookaside cache should have an entry here +* `.gitignore`: Any binary files that exist in a Lookaside cache should have an + entry here **Lookaside Format:** The format for the lookaside cache is: -``` +```text ``` **Note:** *The hash must be cryptographically strong (SHA256 or SHA512).* -### Contrib Repo: github.com/openela-contrib - -This organisation is similar to `openela-main` for existing and new packages. It will serve as a location for all contributions of bug fixes over openela-main, as well as additional packages not available in openela-main. +## Contrib Repo: github.com/openela-contrib -Any tarballs and other binaries shall not be included in the Git repository. It is important to define the pristine upstream sources via their fully qualified URIs in the RPM Spec file `Source#:` tags. `https://` URIs are preferred over others like `http://` or `ftp://`. +This organisation is similar to `openela-main` for existing and new packages. +It will serve as a location for all contributions of bug fixes over +openela-main, as well as additional packages not available in openela-main. +Any tarballs and other binaries shall not be included in the Git repository. +It is important to define the pristine upstream sources via their fully +qualified URIs in the RPM Spec file `Source#:` tags. `https://` URIs are +preferred over others like `http://` or `ftp://`. **DistGit Structure for the OpenELA Contrib Repo:** * `SPECS`: location of the RPM spec file * `SOURCES`: location of all non-binary source files -* `checksums`: list of all non-committed sources which are referenced via `Source#: ` URIs +* `checksums`: list of all non-committed sources which are referenced via + `Source#:` URIs * `maintainers`: list of package maintainers (only for contrib packages) -* `.gitignore`: Any binary files that will be downloaded via `Source#: ` URIs should have an entry here +* `.gitignore`: Any binary files that will be downloaded via `Source#:` URIs + should have an entry here -**Note:** *we might want to put in Git rules to ensure that nobody commits a binary/tarball source into the Git repo.* +**Note:** *we might want to put in Git rules to ensure that nobody commits a +binary/tarball source into the Git repo.* ## References ### Open Patch -Rocky Linux has been using Open Patch to maintain any differences in the package formats. These changes are implemented when the package is imported into the git structure, so branded components of the sources are never persisted or distributed by OpenELA. +Rocky Linux has been using Open Patch to maintain any differences in the +package formats. These changes are implemented when the package is imported +into the git structure, so branded components of the sources are never +persisted or distributed by OpenELA. -The layout is a flat directory structure in the PATCHES directory which contains the Open Patch configurations (files ending with `*.cfg`) and any supporting files necessary. Documentation for Open Patch can be found here: +The layout is a flat directory structure in the PATCHES directory which +contains the Open Patch configurations (files ending with `*.cfg`) and any +supporting files necessary. Documentation for Open Patch can be found here: -Here is an example from Rocky Linux which is almost exactly as OpenELA will use it with a slightly different configuration (e.g. there is a CFG and _supporting directory structure). Here is an example of how Rocky Linux uses Open Patch: +Here is an example from Rocky Linux which is almost exactly as OpenELA will use +it with a slightly different configuration (e.g. there is a CFG and _supporting +directory structure). Here is an example of how Rocky Linux uses Open Patch: From c1e2aab7d9225d1850199712a2ffc73d26f5502e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dirk=20M=C3=BCller?= Date: Thu, 28 Sep 2023 18:25:07 +0200 Subject: [PATCH 4/4] Remove link check again, it seems to be blocked by some links --- .github/workflows/markdown-lint.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/markdown-lint.yaml b/.github/workflows/markdown-lint.yaml index fa99670..8ee94e1 100644 --- a/.github/workflows/markdown-lint.yaml +++ b/.github/workflows/markdown-lint.yaml @@ -10,5 +10,3 @@ jobs: uses: actions/checkout@v2 - name: Run Markdown Lint uses: actionshub/markdownlint@main - - name: Run Link check - uses: gaurav-nelson/github-action-markdown-link-check@v1