Standardize OpenClarity repo structure, hygiene, documentation and remove copy pasta

[ghost]

To improve the developer experience and long term health of the OpenClarity project we should invest in some standardisation around repo management, and have unified front for users and developers to navigate the project. Some things we think should be improved/added:

• repo for managing common workflows and other common configurations (too much copy and pasta right now)
• repo template for creating new repos with all the basics ready to go
• standard template/design for READMEs etc
• standard documentation style/format? perhaps a docs.openclarity.io site?

[justaugustus]

Thanks for filing this issue, Sam!

First things first, for Cisco employees, I would suggest reviewing the OSPO's docs on releasing open source projects.

The "Requirements" and "Best Practices" sections include some guidance and examples to get started with.

• repo for managing common workflows and other common configurations (too much copy and pasta right now)

For organization-level, the .github repo serves as an inheritance point for some GitHub application configurations as well as community health files, like CONTRIBUTING.md, and issue/pull request templates.

The GitHub official docs for this are here: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file

Here are some examples of org-level configurations:

• Allstar: https://github.com/openclarity/.github/tree/main/.github/allstar
• CODEOWNERS: https://github.com/openclarity/.github/blob/main/.github/CODEOWNERS (docs)
• settings.yml: https://github.com/openclarity/.github/blob/main/.github/settings.yml (docs)
• stale.yml: https://github.com/openclarity/.github/blob/main/.github/stale.yml (docs)

For development workflows, I would suggest taking a look at kubernetes-sigs/release-utils.
My team (SIG Release) maintains that project and leverages it for most of our other projects.

Of note in that repo is magefile.go, which is built on Mage (a Golang-based build tool, which has some likenesses to make).

There are a few simple targets that will do things like:

• Run tests
• Verify boilerplate headers for files
• Dependency checks
• Linting (via golangci-lint)
• go build

The mage/ package in kubernetes-sigs/release-utils gives some more examples of what one could do with mage.

So yes, I'd agree that we could benefit from some instrumentation of common workflows here

---

repo template for creating new repos with all the basics ready to go

What would you want to see out of a template repo?

---

standard template/design for READMEs etc

Same question as above.

---

standard documentation style/format? perhaps a docs.openclarity.io site?

We currently have a website for OpenClarity here: https://openclarity.io / https://github.com/openclarity/openclarity.io

I'll make a few suggestions here:

• use Hugo as a static generator
• leverage Hugo modules, replacements, and mounts to import content from multiple repos: https://gohugo.io/hugo-modules/configuration/

An example config snippet might look something like this:

module:
  imports:
    - path: github.com/openclarity/apiclarity
      mounts:
      - source: docs
        target: content/docs/apiclarity
    - path: github.com/openclarity/kubeclarity
      mounts:
      - source: docs
        target: content/docs/kubeclarity
    - path: github.com/openclarity/functionclarity
      mounts:
      - source: docs
        target: content/docs/functionclarity

What that config snippet is saying is:

• import {api,kube,function}clarity repos
• map those repos' docs/ directory to docs/{api,kube,function}clarity on the website

Then we run some sync job in the background to republish the site if docs/ for any of the projects change.

Let me know what you think about these!

[ghost]

What would you want to see out of a template repo?
Same question as above. (for the README)

I think a template repo would lay down the basic foundations/layout for a project (we might need multiple templates one for go projects/other project types), including things like:

• the docs directory with a landing page and an example document
• a starting magefile/Makefile with some of the basic targets already implemented even if empty (build, lint, test, clean)
• a README template with a ToC, a couple of placeholders to indicate what to put there (like ), an empty Why/What section, and then standard Contributing and License sections
• some standard/starter workflows which have lint, test, build, publish steps even if the steps are empty (if we standardise on a mage/Make targets these should be able to be filled out for most projects)
• for go projects we could include a template go.mod as a starting point, and even a hello world main.go so that the targets have something to build and show working even if you've only just cloned the template

[justaugustus]

Opened a separate issue for Code of Conduct: #3

[justaugustus]

(Flagging this as the canonical tracking issue: cisco-open/.github#3)

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.