Add repo setup documentation

Signed-off-by: Celeste Horgan <celeste@cncf.io>
This commit is contained in:
Celeste Horgan 2021-06-22 10:54:12 -07:00
parent 04f22e66af
commit b589d5a7fa
2 changed files with 57 additions and 0 deletions

3
howto/README.md Normal file
View File

@ -0,0 +1,3 @@
# CNCF Techdocs how-to's
This directory contains documentation on how the CNCF techdocs does things. While it is intended for the CNCF techdocs teams' use, we encourage project maintainers to use these documents if you find them helpful!

54
howto/repo-setup.md Normal file
View File

@ -0,0 +1,54 @@
# Repository setup
We recommend that CNCF projects separate docs into their own repository, away from code. This has the following advantages:
- Docs contributors don't need to know the full code build pipeline
- It simplifies repo management/continuous integration setup
For more information:
- The [`cncf/project-template`](https://github.com/cncf/project-template) repository contains many of the files needed to set up a new repository
## CLA/DCO
CLA/DCO should be set up for a project as a part of their project onboarding.
## Licence files
Unless otherwise specified, documentation for CNCF projects is licenced under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/). Code is licenced under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0).
Most CNCF documentation repositories are a mix of code (website code) and documentation itself, so they need two licence files.
For documentation this means you must:
1. Add copyright notices for both the code and the docs to the repository's `README` and the website's footer
For the repository:
```
# License
$PROJECT_NAME is licensed under an [Apache 2.0 license](./LICENSE).
The #PROJECT_NAME documentation is licensed under a [CC-BY-4.0 license](./LICENSE-docs).
```
For the footer:
- [`cncf/hugo-netlify-starter`](https://github.com/cncf/hugo-netlify-starter/blob/main/layouts/partials/footer.html) contains a basic implementation, where the year and project name are parameterized.
2. Add both the CC-BY-4.0 `LICENCE-docs` and Apache 2.0 `LICENCE` files to the root directory of the documentation
- Plain text versions of both [here](https://github.com/cncf/project-template)
For more information:
- Read [CNCF's project copyright guidelines](https://github.com/cncf/foundation/blob/master/copyright-notices.md)
- And the [IP Policy](https://github.com/cncf/foundation/blob/master/charter.md#11-ip-policy)
## README
All docs repositories should have a README file that includes build instructions. Look at [Longhorn's](https://github.com/longhorn/website) for an example, and the [`cncf/project-template`](https://github.com/cncf/project-template) for boilerplate.