- The package or project had to be maintained under **open source license** ( *we make a brief review of the code before the link enters the list* ), [see list of allowed licenses](https://opensource.org/licenses/alphabetical);
- Thoroughly documented (README, pkg.go.dev doc comments, etc.) in english language, so everyone is able to understand the project's intention and how it works
- Tests, where practical. If the library/program is testable, then coverage should be >= 80% for non-data-related packages and >=90% for data related packages. **Notice**: the tests will be reviewed too. We will check your coverage manually if your package's coverage is just a benchmark results.
- The project must have at least one official version-numbered release that allows go.mod files
to list the file by version number. It should be of the form vX.X.X.
## Preparing for review
To make it easy to review, we ask that you do the following to the README file in your proect:
- Add a badge that points to the matching pkg.go.dev link. You can use https://pkg.go.dev/badge/ to create the badge;
- Add a badge that points to the matching Go Report Card report. To generate the report, go to https://goreportcard.com/. Click on the report badge in the upper right corner to see details on how to add the badge to your Readme. The report card must correspond to the latest official release of the project or the current development tip;
- Add a badge that points to a matching coverage report. There are many free ones you can choose from, including codecov, coveralls, and gocover. Also acceptable is generating your own badge as part of a continuous integration process. The report card must correspond to the latest official release of the project or the current development tip;
You will be asked to provide these links when submitting.
## How to add an item to the list
Open a pull request against the README.md document that adds the repository to the list.
- The pull request should add one and only one item to the list;
- The added item should be in alphabetical order within its category;
- The link should be the name of the package or project;
- Descriptions should be clear, concise, and non-promotional;
- Descriptions should follow the link, on the same line and end with a punctuation mark;
- Remember to put a period `.` at end of the project description;
- Links to projects that are version 2 or higher should end in /vX/, where X is the major version number;
Then fill out the template in your PR with the links asked for in your README file.
## Maintenance expectations for projects listed here
To prevent removal from go-awesome, your project must maintain the following quality standards:
- On-going development while maintaining code quality. Official release should be at least once a year if the project is ongoing. OR,
- If development has halted because the project is mature and stable, that can be demonstrated by having no bug reports in the Issues list that are older than 6 months.
- All badges should link to reports showing the most recent official release or current ongoing development. Badges should continue to show the same quality standards as the acceptance criteria above.
Highly recommended but not required:
- A continuous integration process be part of the ongoing development process
- That the project uses a pull-request process and the owners do not commit directly to the repository
- That the pull-request process requires the continuous-integration tests pass before a pull request can be merged
## How to remove an item from the list
- Open a pull request that deletes the line of the project in question.
- Delete the submission template and substitute a description of which criteria the project is not meeting. It should be a combination of:
- The project has not made an official release within the last year and it has open issues.
- The project is not responding to bug reports issued within 6 months of submission.
- The project is not meeting quality standards as indicated by the Go Report Card or Code Coverage tests.
- The quality standards badges have been removed from the README file.
- The project is no longer open-sourced.
- The project is not compatible with any Go version issued within the last year (there is hopefully an open PR about this at the project)
To make sure every PR is checked, we have [team maintainers](MAINTAINERS). Every PR MUST be reviewed by at least one maintainer before it can get merged.
Please open an issue if you would like to discuss anything that could be improved or have suggestions for making the list a more valuable resource. We realize sometimes packages fall into abandonment or have breaking builds for extended periods of time, so if you see that, feel free to change its listing or let us know. We also realize that sometimes projects are just going through transitions or are more experimental in nature. These can still be cool, but we can indicate them as transitory or experimental.
Removal changes will not be applied until they have been pending for a minimum of 1 week (7 days). This grace window benefits projects that may be going through a temporary transition but are otherwise worthy of being on the list.
The official group of maintainers have the final decision on what PRs are accepted. Discussions are made openly in issues. Where there appear to be conflicts, decisions are made by a majority vote where 2/3s of the maintainers are considered a quorum.
Official maintainers must commit to responding to at least one PR per month.
Maintainers are added to or removed by the maintainer group by majority vote where 2/3s of the maintainers are considered a quorum.
