From 7515b470c9c0d574bf6af00d782e69c1f25f8d73 Mon Sep 17 00:00:00 2001 From: Luiz Carvalho Date: Fri, 22 Nov 2024 12:48:39 -0500 Subject: [PATCH 1/3] Consistent use of heading format in README.md Signed-off-by: Luiz Carvalho --- README.md | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 4956f068..62be6040 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,8 @@ -ec-policies -=========== +# ec-policies [Rego][rego] policies related to the Enterprise Contract. - -Getting started for developers ------------------------------- +## Getting started for developers ### Makefile @@ -143,9 +140,7 @@ Run the locally built `ec-cli` command dist/ec_ validate image --verbose --images '{"components": [{"containerImage": "", "name":"my-image", "source":{"git":{"url":"","revision":""}}}]}' --policy 'policy.yaml' --public-key --strict false --ignore-rekor --verbose --output=text - -Policy bundles --------------- +## Policy bundles The policies defined here are bundled and pushed as OCI artifacts using `conftest`. There are three bundles, one for each of the release and pipeline @@ -158,16 +153,12 @@ latest bundles are used. See also the [policy bundle documentation](./antora/docs/modules/ROOT/pages/policy_bundles.adoc). - -Getting started for policy authors ----------------------------------- +## Getting started for policy authors See the [Policy Authoring][authoring] documentation for guidance on contributing to the definition of policy rules. - -See also --------- +## See also * [Policy rule documentation][policydocs] * ["Verify Enterprise Contract" task definition][taskdef] From dc067c475b3694db33cdf71a0c7291dd9f73dec2 Mon Sep 17 00:00:00 2001 From: Luiz Carvalho Date: Fri, 22 Nov 2024 12:57:27 -0500 Subject: [PATCH 2/3] Remove install-tools from docs Signed-off-by: Luiz Carvalho --- README.md | 23 +++++++---------------- 1 file changed, 7 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 62be6040..64f6a01f 100644 --- a/README.md +++ b/README.md @@ -11,23 +11,14 @@ The [`Makefile`](Makefile) contains a lot of useful scripts and commands. Run ### Dependencies -Three tools are required, [`conftest`][conftest], [`opa`][opa], and [`gomplate`][gomplate]. +Go is required for development. Tools like [`conftest`][conftest] and [`opa`][opa] are executed with +the Go binary - they do not need to be installed in your system. See the top of the [go.mod](./go.mod) +file for the minimum version of Go required. -You should be able to install them like this: +Most of the maintainers use [asdf][asdf] to seamlessly use the right version of Go. - make install-tools - -If that doesn't work, installing them manually and making sure they're -available in your path should be fine. - -An optional but useful tool for running tests while developing, (with `make -live-test`), is [`entr`][entr]. You can install it with `dnf`: - - sudo dnf install entr - -And of course you need make if you don't have it already: - - sudo dnf install make +Some, optional, make targets may require additional tooling. For example, `make live-test` requires +[entr][entr] to be installed. ### Formatting @@ -165,10 +156,10 @@ contributing to the definition of policy rules. * [github.com/enterprise-contract][contract] * [github.com/konflux-ci][konflux-ci] +[asdf]: https://asdf-vm.com/ [rego]: https://www.openpolicyagent.org/docs/latest/policy-language/ [conftest]: https://www.conftest.dev/ [opa]: https://www.openpolicyagent.org/docs/latest/ -[gomplate]: https://docs.gomplate.ca/ [entr]: https://github.com/eradman/entr [testing]: https://www.openpolicyagent.org/docs/latest/policy-testing/ [docs]: https://enterprisecontract.dev/ From 70828b5e87af528220370391b4f24516e548f3a2 Mon Sep 17 00:00:00 2001 From: Luiz Carvalho Date: Fri, 22 Nov 2024 13:00:11 -0500 Subject: [PATCH 3/3] Update docs on generating docs Signed-off-by: Luiz Carvalho --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 64f6a01f..1a5a18d6 100644 --- a/README.md +++ b/README.md @@ -33,9 +33,11 @@ The documentation is built using [Antora][antora]. Those docs are published [here][docs]. -To build the documentation locally: +When making changes to policy rules, the docs will likely need to be re-generated. To do so run: - make docs-preview + make generate-docs + +Commit all of the modified files. ### Running tests