Open ghost opened 1 year ago
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:
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:
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:
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:
docs/
directory to docs/{api,kube,function}clarity
on the websiteThen 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!
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:
Opened a separate issue for Code of Conduct: https://github.com/openclarity/.github/issues/3
(Flagging this as the canonical tracking issue: https://github.com/cisco-open/.github/issues/3)
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.
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.
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: