Purpose
The purpose of this project is to marshal various conventions and practices
around publishing Go projects in one place.
It is written in a way where you can check-off each bullet point as you go
along.
☑ Do I have a plush Go Gopher?
List of Recommendations and Guidelines
Below are the recommendations as partitioned by topical area with brief
explanations. Detailed explanations for each of these will be documented
externally.
Publication and Reiteration
This subsection is dedicated to the acts of initially publishing a project or
having an established project undergo a major reiteration. The practical difference between these points is the former means one-time blanket application of
these principles; whereas the latter means ensuring that subsequent changes to
the project uphold and fulfill these principles.
Minimum Criteria
The failure to fulfill any of these usually causes one to discard a project and
look for alternatives.
☐ Licensed: Does the project have a license?
☐ Compiles: Does the project build?
See: publication/compilation.md
☐ Tests Pass: Do the projects tests, if any, pass?
See: publication/tests_pass.md
☐ Code Correctness: Does the code pass format, lint and error checking tools?
See: publication/code_correctness.md
☐ Go Code Review Comments Correctness: Does the project fulfill the
upstream code review
criteria?
See: publication/code_review_comments.md
☐ Build Instructions: Does the project's documentation instruct how to build
the project?
See: publication/build_instructions.md
☐ Test Instructions: Does the project's documentation instruct how to perform
tests?
See: publication/test_instructions.md
☐ README Presence: Does the project's include a documentation entrypoint?
See: publication/documentation_entrypoint.md
☐ Directory Names and Packages Match: Does each package <pkg> statement's
package name match the containing directory name?
See: publication/dir_pkg_match.md
☐ Godoc Correctness: Does the project's
godoc work correctly?
See: publication/godoc_correctness.md
☐ Exporting Only What is Needed: Are any private or internal types
accidentally exported? Are all the types one needs to use the project
correctly exported?
See: TODO
☐ Solving a Real Problem: Does the project fulfill a real necessity or
provide useful learning value?
See: TODO
☐ Idiomaticness: Have the authors even bothered to consult
Effective Go or the
standard library for prior art?
See: TODO
Good Citizen
Projects that provide the following, in addition to the above, set themselves
above the pack.
☐ Contribution Process: Does the project document a contribution process or
workflow (e.g., CONTRIBUTING.md or use of
Gerrit)? Does the project take
affirmative steps to avoid the issues documented in the Unbecoming of a
Hacker?
See: TODO
☐ Code Review Readiness: Does the project note any special nuances or hints
for code review? Are the maintainers sufficiently patient to work with
newcomers to the code review process or willing to document what is
expected?
See: TODO
☐ Issue Reporting Process: Is a process documented for how and where to
report problems?
See: TODO
☐ Contact Information: Does the project list contacts or mailing lists for
maintainers and users?
See: TODO
☐ API Stability and Maturity Grants: Does the project document its
stability guarantees, if any?
See: publication/api_stability_and_maturity.md
☐ Dependency Vendoring: Does the project vendor its dependencies in some
fashion? Bonus points for low-tech. solutions to this.
See: TODO
☐ Continuous Build: Does the project use a continuous build (CB)? Is it
easy for change proposals to be submitted to the CB? Does the team
actively follow the CB?
See: TODO
☐ Presence of Useful Tests: Does the project have tests, specifically ones
that are easy to reason with and maintain?
See: TODO
☐ Minimal Third-Party Dependencies: Does the project avoid unnecessarily
using external packages when the first-party
suffice?
See: TODO
☐ Offers API Examples: If the project exposes a public API, have the
important parts of been documented as
playable examples?
See: TODO
☐ Demonstrates Correct Layout: Does the project lay out its files and
packages in a sane and conventional
way? Is it neither
too sparse nor too dense? Are the executable binaries contained within
a cmd directory?
See: TODO
Extra Credit
These points go above and beyond being a good citizen. Established and mature
projects are likely to fulfill these, though they are certainly not required
for a project to be successful.
☐ References Similar Solutions: Does the project's document actively
reference existing solutions or implementation and offer to compare itself
with them?
See: TODO
☐ Enrolled in Appropriate Directories: Is the project listed in appropriate
registries?
See: TODO
☐ References Formal Research: If the project builds upon formal research,
does the project's documentation prominently link to the supporting
documentation describing the research (e.g., peer reviewed article)?
See: TODO
☐ Roadmap: Does the project offer a formal roadmap?
See: TODO
☐ Benchmarks: In addition to tests, does the project have benchmarks?
See: TODO
☐ Blackbox Tests: In addition to standard tests,
does the project have blackbox tests?
See: TODO
Contributing
Contributions are encouraged. Instructions are documented in
CONTRIBUTING.md.
License
This project is Apache License 2.0.