oracle / oracle/macaron

Improvements to the "Using Macaron" page on Macaron HTML documentation

Open
#291 0 comments 0 reactions 1 assignee View on GitHub

@Demolus13 is already working on this.

Since Jul 22, 2025.

documentation
Dominant language
Python
Stars
210
Forks
36
Avg merge
1d 10h
Merged PRs (30d)
2

Description

Currently, the "Using Macaron" page on the Macaron HTML documentation has a few issues. Possible improvements include:

  • Clearly separating different use cases of Macaron into top-level sections: There should be one top-level section for macaron analyze and another top-level section for macaron verify-policy. Within each top-level section, there can be subsections explaining different options for that action/use case.
  • Focusing on communicating the use case as opposed to lower-level details in the section headings.

The outline may look like the following:

1. Analyze the SLSA posture of a repository
  1.1. Analyze a remote repository
  1.2. With an SBOM
  1.3. With provenance expectations (in cue lang)
  1.4. Analyze a local repository
2. Verify a repository against user-defined expectations (with souffle datalog policy engine)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.