From b3a53961ed0943f1b00063bedf851d99fe6eb77c Mon Sep 17 00:00:00 2001 From: Matthieu Huin Date: Fri, 6 Oct 2023 13:53:42 +0200 Subject: [PATCH] doc on gh.io: fix titles, symlinks not being read properly Change-Id: Idd261c585ee45fec998a7682d4995e419b906011 --- .github/workflows/jekyll-gh-pages.yml | 4 ++ CONTRIBUTING.md | 38 +++++++++++- README.md | 89 ++++++++++++++++++++++++++- doc/README.md | 88 -------------------------- doc/_config.yml | 3 + doc/developer/CONTRIBUTING.md | 37 ----------- zuul.d/jobs.yaml | 2 + 7 files changed, 134 insertions(+), 127 deletions(-) mode change 120000 => 100644 CONTRIBUTING.md mode change 120000 => 100644 README.md delete mode 100644 doc/README.md delete mode 100644 doc/developer/CONTRIBUTING.md diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/jekyll-gh-pages.yml index 735f261c..1928e842 100644 --- a/.github/workflows/jekyll-gh-pages.yml +++ b/.github/workflows/jekyll-gh-pages.yml @@ -22,6 +22,10 @@ jobs: steps: - name: Checkout uses: actions/checkout@v3 + - name: Move README and CONTRIBUTING into the documentation + run: | + cp "${GITHUB_WORKSPACE}/README.md" "${GITHUB_WORKSPACE}/doc/README.md" + cp "${GITHUB_WORKSPACE}/CONTRIBUTING.md" "${GITHUB_WORKSPACE}/doc/developer/CONTRIBUTING.md" - name: Setup Pages uses: actions/configure-pages@v3 - name: Build with Jekyll diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 120000 index 0cfcd237..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1 +0,0 @@ -developer/CONTRIBUTING.md \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..54d4a962 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,37 @@ +# Contributing + +We welcome all contributions to the project! + +General guidelines about contributing to the SF-Operator can be found in this document. +For further details about the code base, testing and hacking the project, please see +the [Developer documentation](doc/developer/index.md). + +## Project repositories + +The main repository of the project is hosted at [softwarefactory-project.io](https://softwarefactory-project.io/r/software-factory/sf-operator). + +The custom container images used by the SF-Operator are defined in the [container-pipeline project](https://softwarefactory-project.io/r/containers) and +published on [quay.io](https://quay.io/organization/software-factory). + +Use the [git-review workflow](https://softwarefactory-project.io/docs/user/contribute.html#create-a-new-code-review) to interact with these projects. + +Repositories with the same name on GitHub are mirrors from **softwarefactory-project.io**, no pull request will be accepted there. + +The MicroShift deployment Ansible role is hosted on [GitHub](https://github.com/openstack-k8s-operators/ansible-microshift-role). Pull Requests are welcome there. + +## Architectural Decision Records (ADRs) + +Any large contribution aiming to modify or implement a functionality must be first validated by the community with +an *[Architectural Decision Record](https://adr.github.io/) (ADR)*. + +ADRs can be created following the [template found in the docs/adr](doc/adr/adr-template.md) directory of +the sf-operator repository. + +## Review Checklist + +Before submitting a change or a patch chain for review, please consider the following checklist: + +1. Are the commit messages clear and explanatory? +1. Do the changes need to be documented in the changelog? +1. Do the changes cover any required modification of the existing documentation? +1. Are the changes tested? We do not require unit testing but do expect functional testing coverage. diff --git a/README.md b/README.md deleted file mode 120000 index 42061c01..00000000 --- a/README.md +++ /dev/null @@ -1 +0,0 @@ -README.md \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 00000000..896aa6cf --- /dev/null +++ b/README.md @@ -0,0 +1,88 @@ +# SF-Operator: a Zuul-based CI infrastructure for OpenShift + + + +Matrix Channel + +Testing only; use in production at your own risks + +## About + +SF-Operator is an Operator that simplifies the deployment and operation of [Zuul](https://zuul-ci.org) and its dependencies (NodePool, Zookeeper, MariaDB, Log Server) on the OpenShift Container Platform. + +It is the natural evolution of the [Software Factory project](https://softwarefactory-project.io): the 3.8.x release of Software Factory saw the containerization of every major service, but was still delivered as RPM packages, in the form of a custom CentOS 7 distribution. +SF-Operator builds upon this containerization effort to move from a distro-centric approach to a cloud-native deployment. +This is also an opportunity to focus on the leanest service suite needed to provide a working gated CI infrastructure; hence a scope reduced to Zuul and its dependencies only. + +SF-Operator is built mostly in Go upon the [Operator Framework](https://operatorframework.io), with the aim of reaching the highest capability level that can be achieved, in order to bring a modern, scalable gated CI alternative to OpenShift users, with the least friction from operation as possible. + +Furthermore, SF-Operator takes advantage of some of the specificities of OpenShift as a container orchestration platform: + +* Improved routes API +* Integration with OLM for streamlined operator and operands' lifecycle management +* If [enabled in OpenShift](https://docs.openshift.com/container-platform/4.13/monitoring/enabling-monitoring-for-user-defined-projects.html#enabling-monitoring-for-user-defined-projects), SF-Operator comes with default monitoring and alerting configurations that can be used out of the box. The default alerting rules are honed from years of maintaining and running several large Zuul deployments at scale for [Fedora](https://fedora.softwarefactory-project.io/zuul/status), [Ansible](https://ansible.softwarefactory-project.io/zuul/status) and [RDO](https://review.rdoproject.org/zuul/status). +* If [enabled](https://docs.openshift.com/container-platform/4.13/logging/cluster-logging.html), OpenShift provides application logs aggregation with its logging subsystem out of the box. + +Finally, we also provide a Command Line Interface (CLI) called sfconfig to simplify common tasks related to the operator, management of the operands, development and testing. + +## Status + +The current project status is: **Alpha - NOT PRODUCTION READY** + +## Capability Levels + +* Level 1 - Basic Install - **8/10** + - Zuul Scheduler: ✅ + - Zuul Executor: ✅ + - Zuul Web: ✅ + - Zuul Merger: ❌ + - Nodepool Launcher: ✅ + - Nodepool Builder: ❌ + - Zookeeper: ✅ + - MariaDB: ✅ + - Log Server: ✅ + - Internal Config Repository, bootstrapped pipelines and default jobs: ✅ +* Level 2 - Seamless upgrades - **2/2** + - Operator: ✅ + - Operands: ✅ +* Level 3 - Full Lifecycle - **1/5** + - SF 3.8.x migration ❌ + - Backup: ❌ + - Restore: ❌ + - Rolling deployments: ❌ + - Reconfiguration: ✅ +* Level 4 - Deep Insights - **1/3** + - Operator metrics: ❌ + - Operand metrics: ✅ + - Alerts: ❌ (WIP) +* Level 5 - Auto pilot - **0/3** + - Auto-scaling : ❌ + - Auto-healing: ❌ + - Auto-tuning: ❌ + +## Getting Started + +* [Installing the Operator ](https://softwarefactory-project.github.io/sf-operator/operator/getting_started.html) +* [Deploying Zuul and dependencies with SF-Operator](https://softwarefactory-project.github.io/sf-operator/deployment/getting_started.html) + +## Documentation + +* [Operator documentation](https://softwarefactory-project.github.io/sf-operator/operator/): for OpenShift cluster administrators, this documentation covers installing SF-Operator and managing the operator's lifecycle. +* [Deployment documentation](https://softwarefactory-project.github.io/sf-operator/deployment/): this documentation covers the essentials for people or teams who intend to deploy and manage Zuul and its dependencies through the SF-Operator. +* [Developer documentation](https://softwarefactory-project.github.io/sf-operator/developer/): this documentation describes how to set up a development and testing environment to develop the SF-Operator. +* [CLI refererence](https://softwarefactory-project.github.io/sf-operator/cli/) +## Getting Help + +Should you have any questions or feedback concerning the SF-Operator, you can: + +* [Join our Matrix channel](https://matrix.to/#/#softwarefactory-project:matrix.org) +* Send an email to [softwarefactory-dev@redhat.com](softwarefactory-dev@redhat.com) +* [File an issue](https://github.com/softwarefactory-project/sf-operator/issues/new) for bugs and feature suggestions + +## Contributing + +Refer to [CONTRIBUTING.md](https://github.com/softwarefactory-project/sf-operator/blob/master/CONTRIBUTING.md). + +## Licence + +Sf-operator is distributed under the [Apache License](https://www.apache.org/licenses/LICENSE-2.0.txt). diff --git a/doc/README.md b/doc/README.md deleted file mode 100644 index 896aa6cf..00000000 --- a/doc/README.md +++ /dev/null @@ -1,88 +0,0 @@ -# SF-Operator: a Zuul-based CI infrastructure for OpenShift - - - -Matrix Channel - -Testing only; use in production at your own risks - -## About - -SF-Operator is an Operator that simplifies the deployment and operation of [Zuul](https://zuul-ci.org) and its dependencies (NodePool, Zookeeper, MariaDB, Log Server) on the OpenShift Container Platform. - -It is the natural evolution of the [Software Factory project](https://softwarefactory-project.io): the 3.8.x release of Software Factory saw the containerization of every major service, but was still delivered as RPM packages, in the form of a custom CentOS 7 distribution. -SF-Operator builds upon this containerization effort to move from a distro-centric approach to a cloud-native deployment. -This is also an opportunity to focus on the leanest service suite needed to provide a working gated CI infrastructure; hence a scope reduced to Zuul and its dependencies only. - -SF-Operator is built mostly in Go upon the [Operator Framework](https://operatorframework.io), with the aim of reaching the highest capability level that can be achieved, in order to bring a modern, scalable gated CI alternative to OpenShift users, with the least friction from operation as possible. - -Furthermore, SF-Operator takes advantage of some of the specificities of OpenShift as a container orchestration platform: - -* Improved routes API -* Integration with OLM for streamlined operator and operands' lifecycle management -* If [enabled in OpenShift](https://docs.openshift.com/container-platform/4.13/monitoring/enabling-monitoring-for-user-defined-projects.html#enabling-monitoring-for-user-defined-projects), SF-Operator comes with default monitoring and alerting configurations that can be used out of the box. The default alerting rules are honed from years of maintaining and running several large Zuul deployments at scale for [Fedora](https://fedora.softwarefactory-project.io/zuul/status), [Ansible](https://ansible.softwarefactory-project.io/zuul/status) and [RDO](https://review.rdoproject.org/zuul/status). -* If [enabled](https://docs.openshift.com/container-platform/4.13/logging/cluster-logging.html), OpenShift provides application logs aggregation with its logging subsystem out of the box. - -Finally, we also provide a Command Line Interface (CLI) called sfconfig to simplify common tasks related to the operator, management of the operands, development and testing. - -## Status - -The current project status is: **Alpha - NOT PRODUCTION READY** - -## Capability Levels - -* Level 1 - Basic Install - **8/10** - - Zuul Scheduler: ✅ - - Zuul Executor: ✅ - - Zuul Web: ✅ - - Zuul Merger: ❌ - - Nodepool Launcher: ✅ - - Nodepool Builder: ❌ - - Zookeeper: ✅ - - MariaDB: ✅ - - Log Server: ✅ - - Internal Config Repository, bootstrapped pipelines and default jobs: ✅ -* Level 2 - Seamless upgrades - **2/2** - - Operator: ✅ - - Operands: ✅ -* Level 3 - Full Lifecycle - **1/5** - - SF 3.8.x migration ❌ - - Backup: ❌ - - Restore: ❌ - - Rolling deployments: ❌ - - Reconfiguration: ✅ -* Level 4 - Deep Insights - **1/3** - - Operator metrics: ❌ - - Operand metrics: ✅ - - Alerts: ❌ (WIP) -* Level 5 - Auto pilot - **0/3** - - Auto-scaling : ❌ - - Auto-healing: ❌ - - Auto-tuning: ❌ - -## Getting Started - -* [Installing the Operator ](https://softwarefactory-project.github.io/sf-operator/operator/getting_started.html) -* [Deploying Zuul and dependencies with SF-Operator](https://softwarefactory-project.github.io/sf-operator/deployment/getting_started.html) - -## Documentation - -* [Operator documentation](https://softwarefactory-project.github.io/sf-operator/operator/): for OpenShift cluster administrators, this documentation covers installing SF-Operator and managing the operator's lifecycle. -* [Deployment documentation](https://softwarefactory-project.github.io/sf-operator/deployment/): this documentation covers the essentials for people or teams who intend to deploy and manage Zuul and its dependencies through the SF-Operator. -* [Developer documentation](https://softwarefactory-project.github.io/sf-operator/developer/): this documentation describes how to set up a development and testing environment to develop the SF-Operator. -* [CLI refererence](https://softwarefactory-project.github.io/sf-operator/cli/) -## Getting Help - -Should you have any questions or feedback concerning the SF-Operator, you can: - -* [Join our Matrix channel](https://matrix.to/#/#softwarefactory-project:matrix.org) -* Send an email to [softwarefactory-dev@redhat.com](softwarefactory-dev@redhat.com) -* [File an issue](https://github.com/softwarefactory-project/sf-operator/issues/new) for bugs and feature suggestions - -## Contributing - -Refer to [CONTRIBUTING.md](https://github.com/softwarefactory-project/sf-operator/blob/master/CONTRIBUTING.md). - -## Licence - -Sf-operator is distributed under the [Apache License](https://www.apache.org/licenses/LICENSE-2.0.txt). diff --git a/doc/_config.yml b/doc/_config.yml index abaf44d4..0e4b6f5d 100644 --- a/doc/_config.yml +++ b/doc/_config.yml @@ -1,3 +1,6 @@ +title: SF-Operator Documentation +# description: + remote_theme: pages-themes/cayman@v0.2.0 plugins: - jekyll-remote-theme diff --git a/doc/developer/CONTRIBUTING.md b/doc/developer/CONTRIBUTING.md deleted file mode 100644 index 54d4a962..00000000 --- a/doc/developer/CONTRIBUTING.md +++ /dev/null @@ -1,37 +0,0 @@ -# Contributing - -We welcome all contributions to the project! - -General guidelines about contributing to the SF-Operator can be found in this document. -For further details about the code base, testing and hacking the project, please see -the [Developer documentation](doc/developer/index.md). - -## Project repositories - -The main repository of the project is hosted at [softwarefactory-project.io](https://softwarefactory-project.io/r/software-factory/sf-operator). - -The custom container images used by the SF-Operator are defined in the [container-pipeline project](https://softwarefactory-project.io/r/containers) and -published on [quay.io](https://quay.io/organization/software-factory). - -Use the [git-review workflow](https://softwarefactory-project.io/docs/user/contribute.html#create-a-new-code-review) to interact with these projects. - -Repositories with the same name on GitHub are mirrors from **softwarefactory-project.io**, no pull request will be accepted there. - -The MicroShift deployment Ansible role is hosted on [GitHub](https://github.com/openstack-k8s-operators/ansible-microshift-role). Pull Requests are welcome there. - -## Architectural Decision Records (ADRs) - -Any large contribution aiming to modify or implement a functionality must be first validated by the community with -an *[Architectural Decision Record](https://adr.github.io/) (ADR)*. - -ADRs can be created following the [template found in the docs/adr](doc/adr/adr-template.md) directory of -the sf-operator repository. - -## Review Checklist - -Before submitting a change or a patch chain for review, please consider the following checklist: - -1. Are the commit messages clear and explanatory? -1. Do the changes need to be documented in the changelog? -1. Do the changes cover any required modification of the existing documentation? -1. Are the changes tested? We do not require unit testing but do expect functional testing coverage. diff --git a/zuul.d/jobs.yaml b/zuul.d/jobs.yaml index 7c4cc4ae..4e47542c 100644 --- a/zuul.d/jobs.yaml +++ b/zuul.d/jobs.yaml @@ -35,6 +35,7 @@ irrelevant-files: - ".*.md$" - "doc/.*" + - ".github/.*" required-projects: - name: software-factory/sf-infra roles: @@ -71,6 +72,7 @@ irrelevant-files: - ".*.md$" - "doc/.*" + - ".github/.*" required-projects: - name: software-factory/sf-infra roles: