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?

See: publication/licensing.md

☐ 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.