Rules documentation

[clbarrell]

Starting a new Rules page for Matt and Laura.

[gilesgas]

Thanks very much for this contribution @clbarrell !!

At least one of these build errors in this PR is occurring because there's no entry for this page in the nav.yml file. For all new pages, you need to explicitly specify a page location in the nav (the docs page hierarchy on the left) for the Buildkite Docs site to work. This is done by creating an entry for it in nav.yml.

@clbarrell , whereabouts were you thinking of adding this page to in the nav? Is it meant to be part of:

1. Clusters (i.e. is this feature only relevant to clusters), where this new Pipeline rules page should be located within the Clusters page hierarchy.
2. A more general topic on security, where this new page should be located within the Security page hierarchy of the Pipelines docs.

There is some description of this in the Working with the docs site section of the Markdown syntax style guide. This content is going to be pulled out into its own 'public contributor's guide' page.

[gilesgas]

Sorry @clbarrell , I didn't acknowledge the 'draft' label you added to this PR. I've converted this PR to a draft using the 'convert to draft' feature at the top-right (under Reviewers).

Please click Ready for review when it's ready to review 😁

[buildkite-docs-bot]

Preview URL: https://2932--bk-docs-preview.netlify.app

[matthewborden]

This question could initially be answered by the answer to the question—are rules only applicable to interactions between different pipelines in Buildkite, or could the source and target resources be different things, like different features of Buildkite products, or third-party things?

Initially Rules only supports pipelines, but in the future it could be extended to support other resources (other Buildkite products). For now I think it makes sense to live within the Pipelines product docs, but can see it being promoted into the Platform section of the docs when we introduce non-pipelines rules, it's a platform capability but starting out scoped to only pipelines.

[gilesgas]

Initially Rules only supports pipelines, but in the future it could be extended to support other resources (other Buildkite products). For now I think it makes sense to live within the Pipelines product docs, but can see it being promoted into the Platform section of the docs when we introduce non-pipelines rules, it's a platform capability but starting out scoped to only pipelines.

Thanks for clarifying this! Therefore, I feel it makes sense that for the time being, we keep this as a top-level nav section in the Pipelines since moving it within the Configure pipelines section might imply a more narrowed scope (i.e. just for use within pipelines only, as opposed to use with other features of Buildkite Pipelines as a product).

Edit: In retrospect, I should've realised clusters transcends pipelines, which adds more weight to its current location.

[gilesgas]

Just implemented some updates to the PR, particularly on the 'managing rules' page. These involve the following points:

• There's no need to put content into partials that are only used once throughout the Buildkite Docs. Partials allow content re-use. If a partial is only used once, it should be written directly into its source page. Best to start doing this first and then decide to move the content into a partial if that content needs to be re-used somewhere else in the docs, even elsewhere on the same page. Anyway, I removed 3 partials that weren't re-used, and reimplemented them on the managing rules page itself.

• Best not to mix REST and GraphQL API methods for obtaining specific values for a written procedure that just focuses on either the REST API or GraphQL only. For a REST API procedure, all 'where:' bullet points should only reference either the Buildkite interface or REST way of obtaining the bullet point's value/s. Don't add a GraphQL method/way for doing this too as it complicates the content.

• I changed some methods (REST ones) from 'getting a pipeline' to 'listing pipelines', since unlike getting a pipieline, you don't need to obtain the pipeline slug beforehand for listing pipelines.

• I added what the rule / type were, since this was important and shouldn't be missed, even though it's obvious. Assume that anyone can enter any specific point in the docs (e.g. create a rule > using the REST API) without needing to jump around elsewhere for info on how to obtain values for the request.

[gilesgas]

FYI only (for future docs contributions) ... Markdown syntax does not render into HTML, when this syntax is used within HTML tables in a Markdown file.

Therefore, I had to convert this Markdown link into its HTML equivalent.

[gilesgas]

Ready to merge!

[gilesgas]

Adding one more tweak.