ansible-community / ansible-community/github-docs-build

Add a validate job to the workflows

Open
#33 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Jinja
Stars
13
Forks
10
Avg merge
10h 14m
Merged PRs (30d)
1

Description

With #27 , we have some control over how strict the build is.

The way I see it, there should be a build that has the strictest settings, for validation, while builds for publishing (especially in PRs) should use the most lenient options, to give us the best chance of a publishable build (even if some pages have errors), because that's more useful for checking rendered output and comparing changes.

By using separate jobs, we can get published docs whenever possible, while still having the validate job "fail" the CI until all errors/warnings are fixed.

Currently using this pattern in `community.hashi_vault` and `lowlydba.sqlserver`, but it could use support here to avoid having to repeat some things.

In the push workflows, we can achieve this with the push reusable workflow already, with caveats:
- we can't disable the artifact upload, so we set the name to `_unused`
- the underlying action can already disable artifact upload, we should expose that to the push workflow

In PR, the only reason we can't use the push reusable workflow is because it has no way to specify the ref, so:
- we kind of repeat what the push workflow does but use the merge commit for checkout
- the push workflow could take a ref input
- we skip on PR close events (no need to validate there)
- should we add a validate reusable workflow?
- if so, we cannot use it in the other reusable workflows (can't nest reusables), so it will be some duplication
- but it does provide a convenient use for users who want to the run the validations separately
- inclusion of a validate job in PR and Push workflows
- good (opinionated) default imo
- provide option to skip it? easy to do, some collections maybe don't want to fail CI on this
- if optional job is used in `needs:` it complicates the dependent jobs a little if you still want them to run; need to use `if: always() && needs.validate.result [is skipped or successful]` type of conditional
- validate is not needed in `needs:` for PRs, but probably would be for push workflows that also publish, if that validation should prevent publish; in theory the push workflow can just be invoked most strictly all the time, removing the need for a separate validation workflow, but this won't work for pre-init'd use cases, unless strictness can be controlled on build as well as init.

Last point leads to the idea of:
- `anstibull-docs sphinx-init` generated `build.sh` could be updated to take arguments, allowing for some override of options chosen at init time

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading the existing push reusable workflow, the PR workflows, the artifact-upload action, and the `sphinx-init` generated `build.sh`. Trace how refs, artifact uploads, strictness, and dependent jobs are handled. Done means the agreed design provides a strict validation job while preserving useful publishing builds and covers the documented push and PR cases.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions
Domain
ci-cd
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.