For general questions about gordian, gcosmos,
or any other repository in the gordian-engine organization,
use the gordian-engine discussion board.
Only file issues for bug reports and feature requests.
Simon Tatham's article, How to Report Bugs Effectively is a short article worth reading in its entirety.
Follow the existing conventions in the repository against which you are opening the pull request.
The rest of this section details some of the commonly missed conventions.
There are many resources on writing good commit messages. This article from cbeams is thorough and contains many source references.
We generally follow Conventional Commits. This helps when browsing commits to understand the general scope of a change. As a result of the prefixes imposed by Conventional Commits, we don't tyipcally closely follow the 50-character subject rule in commit messages.
Where possible, we use test-driven development within Gordian projects. Both bug fixes and new features are expected to include tests.
Tests are expected to pass with the
data race detector,
i.e. running go test -race should succeed.
We use semantic linefeeds for markdown files and comments. Brandon Rhodes has a good article explaining what semantic linefeeds are and why to follow that pattern.
By starting a new line at the end of each sentence, and splitting sentences themselves at natural breaks between clauses, a text file becomes far easier to edit and version control.
Core maintainers frequently read diffs, and semantic linefeeds make documentation and comment diffs readable.
There are conventions for using documentation comments in Go. The official docs detail the conventions and available docuemtnation features.
One of the most commonly missed godoc patterns is:
As with packages and funcs, doc comments for types start with complete sentences naming the declared symbol.
Complete sentences include punctuation.
Use goimports to format your Go code.
All Gordian repositories have a .editorconfig file in the root.
Make sure your editor respects the configuration.