Enhance GitHub Actions: Publish PR and Push Previews as Artifacts to Release Assets and GitHub Pages

[cofinoa]

This issue documents a technical enhancement introduced in PR #568 to streamline the documentation build process for forked repositories. This update ensures that the gh-pages branch is automatically created if it does not already exist in a fork, enabling consistent publishing of documentation across forks.

Once the branch is created, it is populated with the necessary build artifacts, including the CF Conventions and Conformance documents in both PDF and HTML formats. These files are linked from a basic index file template located in .github/index.html, providing easy access to the documentation in each fork. This enhancement enables contributors and maintainers of forked repositories to maintain an up-to-date and accessible version of the CF documentation, improving the deployment experience.

To complete the setup, forks must activate GitHub Pages and set the publishing source to the / directory on the gh-pages branch.

[JonathanGregory]

Thanks a lot, Antonio. This is a really valuable enhancement to procedures, which I've found useful already. I've been using it for the "leap seconds" issue.

There is a limitation that you can do this only for one branch, whereas you might have several branches for different issues at the same time. However, that's a limitation of GitHub Pages.

[cofinoa]

@JonathanGregory Yes, I’ve encountered that limitation myself, especially with issue #513.

A reasonable approach might be to create a directory in the gh-pages branch, named after each branch being pushed. This way, each branch can have its own published content within a dedicated directory in gh-pages.

Managing this with PRs is also possible, but it could introduce some security concerns that may be difficult to overcome.

[larsbarring]

I fully agree with Jonathan -- indeed a very useful enhancement! 👍

[cofinoa]

@JonathanGregory

I have created an experimental and rudimentary approach for publishing artifacts from more than just the "main" branch. You can check it here:
https://cofinoa.github.io/cf-conventions/

With this setup, any push to any branch (except gh-pages) is published under a directory named after the branch, inside the branch directory. This makes it possible to publish progress (e.g., each push) for any branch in the forked repository.

Please let me know your thoughts or suggestions!

[JonathanGregory]

That's perfect, @cofinoa! Thanks. I can try it if you like. How would I do that?

[cofinoa]

@JonathanGregory

I suggest proceeding with merging the related PR #568, which introduces key improvements to the GitHub Action workflow for building and publishing the CF conventions documentation.

Summary of Improvements

1. Refactored Workflow: The workflow has been streamlined for better clarity and maintainability by restructuring jobs and steps.
2. Enhanced Automation:
   • Documentation Build: Builds HTML and PDF outputs using asciidoctor in a robust and consistent manner.
   • GitHub Pages Deployment: Automatically deploys the latest build to the gh-pages branch, organizing the output into directories based on the type of event:
     • Release Events: Documentation is uploaded under release/<tag_name> (e.g., release/v1.9.0).
     • Branch Events: Documentation is uploaded under branch/<branch_name> (e.g., branch/main).
     • Tag Events: Documentation is uploaded under tag/<tag_name> (e.g., tag/v1.9.0).
   • Release Artifacts: On release events, the workflow uploads documentation as release assets to the release page.
3. Improved Error Handling:
   • Pre-checks ensure that all prerequisites (e.g., branch setup, artifacts) are met before proceeding, reducing the likelihood of failures.

How to Use the Updated Workflow in a Fork

1. Sync Your Fork:

   • Merge PR Updating build process and gh-pages fork publications #568 into your main branch.
   • If your fork has diverged, ensure it is synced with the upstream repository.

2. Enable GitHub Actions:

   • Ensure that Actions are enabled in the fork's settings.
   • The workflow is designed to trigger automatically on the following events:
     • Pushes to ANY branch (excluding gh-pages).
     • Pull requests targeting main.
     • Release events.

3. Directory Structure in gh-pages:

   • The workflow automatically organizes documentation in the gh-pages branch:
     • For release events: release/<tag_name> (e.g., release/v1.9.0).
     • For branch builds: branch/<branch_name> (e.g., branch/main).
     • For tag events: tag/<tag_name> (e.g., tag/v1.9.0).

4. Testing the Workflow:

   • Use the Actions tab in your fork to manually trigger a workflow run.
   • Simulate a release event, in your fork, to verify that artifacts are correctly uploaded to the release page.

By adopting this updated workflow, the process for maintaining and publishing the CF conventions documentation will be more reliable and easier to manage. Please let me know if you have further questions or suggestions.