2.0 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 (path is
../golib/wiki/<package>.md) - 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:
- Link to wiki page from the Home page
- 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 make any changes to master. Checkout a branch to work on new features Version numbers are specified using git tags. 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