Merge pull request #263 from raspberrypi/develop

Deploy to production

Author: mudge

.github/workflows/build.yml

@@ -1,21 +1,17 @@
 name: Build
 
 on:
+  workflow_dispatch:
   push:
     branches:
       - master
+      - develop
   pull_request:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, web]
     steps:
-      - name: Only allow pull requests based on master from the develop branch of the current repository
-        if: ${{ github.base_ref == 'master' && !(github.head_ref == 'develop' && github.event.pull_request.head.repo.full_name == github.repository) }}
-        run: |
-          echo "Pull requests based on master can only come from the develop branch of this repository"
-          echo "Please check your base branch as it should be develop by default"
-          exit 1
       - uses: actions/checkout@v5
       - uses: actions/setup-python@v6
         with:
@@ -42,15 +38,58 @@ jobs:
         run: make build_doxygen_adoc
       - name: Build documentation
         run: make -j 2
+      - uses: actions/upload-artifact@v4
+        with:
+          name: documentation
+          path: documentation/html/
+          if-no-files-found: error
+          retention-days: 1
+          include-hidden-files: true
+
+  deploy-staging:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: staging
+      url: ${{ vars.STAGING_URL }}
+    if: ${{ github.ref == 'refs/heads/develop' }}
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/download-artifact@v5
+        with:
+          name: documentation
+          path: documentation/html
+      - name: Deploy to Mythic Beasts
+        uses: ./.github/actions/deploy-action
+        with:
+          private_ssh_key: ${{ secrets.DEPLOY_SSH_KEY }}
+          public_bastion_host_keys: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
+          bastion_host: ${{ secrets.DEPLOY_BASTION_HOST }}
+          primary_host: ${{ secrets.DEPLOY_PRIMARY_HOST }}
+          secondary_host: ${{ secrets.DEPLOY_SECONDARY_HOST }}
+          source: documentation/html/
+          destination: documentation
+
+  deploy-production:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: production
+      url: ${{ vars.PRODUCTION_URL }}
+    if: ${{ github.ref == 'refs/heads/master' }}
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/download-artifact@v5
+        with:
+          name: documentation
+          path: documentation/html
       - name: Deploy to Mythic Beasts
-        if: ${{ github.ref == 'refs/heads/master' }}
         uses: ./.github/actions/deploy-action
         with:
           private_ssh_key: ${{ secrets.DEPLOY_SSH_KEY }}
           public_bastion_host_keys: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
           bastion_host: ${{ secrets.DEPLOY_BASTION_HOST }}
           primary_host: ${{ secrets.DEPLOY_PRIMARY_HOST }}
           secondary_host: ${{ secrets.DEPLOY_SECONDARY_HOST }}
-          # this needs to match destination: in _config.yml
           source: documentation/html/
           destination: documentation

.github/workflows/mirror.yml

@@ -0,0 +1,19 @@
+name: Mirror repository
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+jobs:
+  mirror:
+    runs-on: [self-hosted, web]
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: master
+          token: ${{ secrets.DOCUMENTATION_REPO_TOKEN }}
+          fetch-depth: 0
+      - run: git remote add documentation https://github.com/raspberrypi/documentation.git
+      - run: git push --force documentation master

CONTRIBUTING.md

@@ -1,36 +1,45 @@
 # Contributing to the Raspberry Pi Documentation
 
-The Raspberry Pi Documentation website is built from Asciidoc source using:
+Welcome to the [public repository](https://github.com/raspberrypi/documentation/) for the Raspberry Pi documentation. This repository contains the Asciidoc source and the Jekyll-based build tools for the HTML documentation hosted at the [Raspberry Pi documentation site](https://www.raspberrypi.com/documentation/).
 
-* [Asciidoctor](https://asciidoctor.org/)
-* [Jekyll](https://jekyllrb.com/)
-* [jekyll-asciidoc](https://github.com/asciidoctor/jekyll-asciidoc)
-* Python
+The public repository is a mirror of an internal repository from which the site is built. The master branch of this repository is automatically kept up to date with the latest published content on the [website](https://www.raspberrypi.com/documentation/).
 
-The website automatically deploys to [www.raspberrypi.com/documentation](https://www.raspberrypi.com/documentation) using GitHub Actions when new commits appear in the `master` branch.
+We encourage and value all types of contributions from our community. Please make sure to read the following section before making your contribution. It makes it a lot easier for the Raspberry Pi Technical Documentation team (the maintainers) and smooths out the experience for all involved. We look forward to your contributions.
 
 ## Contribute
 
-To contribute or update documentation:
+To suggest changes to this documentation:
 
-1. Create a fork of this repository on your GitHub account.
+1. Create a fork of the `raspberrypi/documentation` repository on your GitHub account.
 
-1. Make changes in your fork. Start from the default `develop` branch.
+1. Make changes in your fork. Start by branching from the default `master` branch.
 
 1. Read our [style guide](https://github.com/raspberrypi/style-guide/blob/master/style-guide.md) to ensure that your changes are consistent with the rest of our documentation. Since Raspberry Pi is a British company, be sure to include all of your extra `u`s and transfigure those `z`s (pronounced 'zeds') into `s`s!
 
 1. [Open a pull request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) against this repository.
 
-1. The maintainers will assess and copy-edit the PR. This can take anywhere from a few minutes to a few days, depending on the size of your PR, the time of year, and the availability of the maintainers.
+1. The maintainers assess the PR. We hope to get back to you within a fortnight, but this might vary depending on the size of your PR, the time of year, and the availability of the maintainers.
 
-1. After making any requested improvements to your PR, the maintainers will accept the PR and merge your changes into `develop`.
+1. What happens next depends on the content of the PR and whether it inspires any wider changes:
 
-1. When the maintainers next release the documentation by merging `develop` into `master`, your changes will go public on the production documentation site.
+   * If we have questions about the PR, we work with you to understand what you are going for and how best the docs can achieve it.
+   * If your PR can be included as-is, we use the patch mechanism to bring it across to the internal repository and commit it there. When the change is published on the Raspberry Pi Documentation website, it is mirrored to the public repository and your PR closes automatically.
+   * If your PR needs significant editing or prompts a wider change to the documentation, we take on that work in our internal repository. We'll let you know if that's the case and how long we expect it to take.
+   If we don't bring your initial changes over as a patch, we use the [co-author mechanism](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors) to ensure you get credit for your contribution.
 
 Alternatively, [open an issue](https://github.com/raspberrypi/documentation/issues) to discuss proposed changes.
 
 ## Build
 
+The Raspberry Pi Documentation website is built from Asciidoc source using:
+
+* [Asciidoctor](https://asciidoctor.org/)
+* [Jekyll](https://jekyllrb.com/)
+* [jekyll-asciidoc](https://github.com/asciidoctor/jekyll-asciidoc)
+* Python
+
+The website deploys to [www.raspberrypi.com/documentation](https://www.raspberrypi.com/documentation) from an internal repository that is mirrored to the [public repository](https://github.com/raspberrypi/documentation/).
+
 ### Install dependencies
 
 To build the Raspberry Pi documentation locally, you'll need Ruby, Python, and the Ninja build system.
@@ -54,7 +63,7 @@ Close and re-launch your terminal window to use the new dependencies and configu
 
 #### macOS
 
-If you don't already have it, we recommend installing the [Homebrew](https://brew.sh/) package manager: 
+If you don't already have it, we recommend installing the [Homebrew](https://brew.sh/) package manager:
 
 ```console
 $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

README.md

@@ -1,9 +1,9 @@
 <div align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/raspberrypi/documentation/refs/heads/develop/pi_dark.svg">
-    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/raspberrypi/documentation/refs/heads/develop/pi_light.svg">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/raspberrypi/documentation/refs/heads/master/pi_dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/raspberrypi/documentation/refs/heads/master/pi_light.svg">
     <img alt="Raspberry Pi: computers and microcontrollers"
-         src="https://raw.githubusercontent.com/raspberrypi/documentation/refs/heads/develop/pi_light.svg"
+         src="https://raw.githubusercontent.com/raspberrypi/documentation/refs/heads/master/pi_light.svg"
          width="16%">
   </picture>
 
@@ -19,4 +19,4 @@ This repository contains the source and tools used to build the [Raspberry Pi Do
 
 ## Licence
 
-The Raspberry Pi documentation is [licensed](https://github.com/raspberrypi/documentation/blob/develop/LICENSE.md) under a Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA). Documentation tools (everything outside of the `documentation/` subdirectory) are licensed under the [BSD 3-Clause](https://opensource.org/licenses/BSD-3-Clause) licence.
+The Raspberry Pi documentation is [licensed](https://github.com/raspberrypi/documentation/blob/master/LICENSE.md) under a Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA). Documentation tools (everything outside of the `documentation/` subdirectory) are licensed under the [BSD 3-Clause](https://opensource.org/licenses/BSD-3-Clause) licence.

_config.yml

@@ -21,7 +21,6 @@ url: "https://www.raspberrypi.com/documentation" # the base hostname & protocol
 githuburl: "https://github.com/raspberrypi/documentation/"
 mainsite: https://raspberrypi.com/
 githubbranch: master
-githubbranch_edit: develop
 
 # Build settings
 theme: minima

scripts/create_build_adoc.py

@@ -54,7 +54,7 @@ def check_no_markdown(filename):
     with open(github_edit) as edit_fh:
         edit_template = edit_fh.read()
         template_vars = {
-            'github_edit_link': os.path.join(site_config['githuburl'], 'blob', site_config['githubbranch_edit'], src_adoc)
+            'github_edit_link': os.path.join(site_config['githuburl'], 'blob', site_config['githubbranch'], src_adoc)
         }
         edit_text = re.sub(r'{{\s*(\w+)\s*}}', lambda m: template_vars[m.group(1)], edit_template)
 

scripts/create_build_adoc_include.py

@@ -36,7 +36,7 @@ def check_no_markdown(filename):
     with open(github_edit) as edit_fh:
         edit_template = edit_fh.read()
         template_vars = {
-            'github_edit_link': os.path.join(site_config['githuburl'], 'blob', site_config['githubbranch_edit'], src_adoc)
+            'github_edit_link': os.path.join(site_config['githuburl'], 'blob', site_config['githubbranch'], src_adoc)
         }
         edit_text = re.sub(r'{{\s*(\w+)\s*}}', lambda m: template_vars[m.group(1)], edit_template)