1.8 KiB
GOLIB Rules
- 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)
-
All features should have tests. Any changes to existing features or additional features implemented should have tests created and/or updated
-
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