45 lines
1.8 KiB
Markdown
45 lines
1.8 KiB
Markdown
# GOLIB Rules
|
|
|
|
1. All changes should be documented
|
|
Documentation is done in a few ways:
|
|
- docstrings
|
|
- README.md
|
|
- doc.go
|
|
- wiki
|
|
|
|
The README for each module should be laid out as follows:
|
|
- Title and description with version number
|
|
- Feature list (DO NOT USE EMOTICONS)
|
|
- Installation (go get)
|
|
- Quick Start (brief example of setting up and using)
|
|
- Documentation links to the wiki
|
|
- Additional information (e.g. supported databases if package has database features)
|
|
- License
|
|
- Contributing
|
|
- Related projects (if relevant)
|
|
|
|
Docstrings and doc.go should conform to godoc standards.
|
|
Any Config structs with environment variables should have their docstrings match the format
|
|
`// ENV ENV_NAME: Description (required <optional condition>) (default: <default value>)`
|
|
where the required and default fields are only present if relevant to that variable
|
|
|
|
The wiki is located at ~/projects/golib-wiki and should be laid out as follows:
|
|
- Title and description with version number
|
|
- Installation
|
|
- Key Concepts and features
|
|
- Quick start
|
|
- Configuration (explicity prefer using ConfigFromEnv for packages that support it)
|
|
- Detailed sections on how to use all the features
|
|
- Integration (many of the packages in this repo are designed to work in tandem. any close integration with other packages should be mentioned here)
|
|
- Best practices
|
|
- Troubleshooting
|
|
- See also (links to other related or imported packages from this repo)
|
|
- Links (GoDoc api link, source code, issue tracker)
|
|
|
|
2. All features should have tests.
|
|
Any changes to existing features or additional features implemented should have tests created and/or updated
|
|
|
|
3. Version control
|
|
Do not change version numbers. When updating documentation, append the branch name to the version number.
|
|
Changes made to the golib-wiki repo should be made under the same branch name as the changes made in this repo
|