awesome/awesome-go
1
0
Fork 0
mirror of https://github.com/avelino/awesome-go.git synced 2024-11-28 16:56:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

Modifications based on feedback

Browse Source
This commit is contained in:
spekary 2022-02-26 07:40:36 -08:00 committed by Avelino
parent 733b7e8f3f
commit 36d3989654
1 changed files with 52 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
CONTRIBUTING.md
View File

@ -12,54 +12,56 @@ even if you are a _developer reviewing your contribution_. **Sorry if we can't m
To set this list apart from and complement the excellent [Go wiki Projects page](https://golang.org/wiki/Projects),
and other lists, awesome-go is a specially curated list for high-quality, actively maintained Go packages and resources.
- At least 3 items are needed to create a new category;
- 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);
Please contribute links to packages/projects you have used or are familiar with. This will help ensure high-quality entries.
If you removed our PR template you can find it [here](https://github.com/avelino/awesome-go/blob/main/.github/PULL_REQUEST_TEMPLATE.md).
## Quality standards
## General quality standards
To be on the list, project repositories should adhere to these quality standards
To be on the list, project repositories should adhere to the following quality standards
(https://goreportcard.com/report/github.com/ **github_user** / **github_repo**):
- Code functions as documented and expected;
- Generally useful to the wider community of Go programmer
- Actively maintained
- Regular, recent commits
- Or, for finished projects, issues and pull requests are responded to generally within 2 weeks
- Stable or progressing toward stable
- 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 has a Go Report Card value of A.
- 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.
- have an **open source license**, [see list of allowed licenses](https://opensource.org/licenses/alphabetical);
- function as documented and expected;
- be generally useful to the wider community of Go programmers;
- be actively maintained with:
- Regular, recent commits;
- Or, for finished projects, issues and pull requests are responded to generally within 2 weeks;
- be stable or progressing toward stable;
- be thoroughly documented (README, pkg.go.dev doc comments, etc.) in the english language, so everyone is able to understand the project's intention and how it works;
- if the library/program is testable, then coverage should be >= 80% for non-data-related packages and >=90% for data related packages. (**Note**: the tests will be reviewed too. We will check your coverage manually if your package's coverage is just a benchmark results);
- have at least one official version-numbered release that allows go.mod files to list the file by version number, of the form vX.X.X.
Categories must have at least 3 items.
## 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;
Projects listed must have the following in their documentation. When submitting, you will be asked
to provide them.
You will be asked to provide these links when submitting.
- A link to the project's pkg.go.dev page
- A link to the project's Go Report Card report
- A link to a code coverage report
One way to accomplish the above is to add badges to your project's README file.
- Use https://pkg.go.dev/badge/ to create the pkg.go.dev link.
- Go to https://goreportcard.com/ to generate a Go Report Card report, then click on the report badge in the upper right corner to see details on how to add the badge to your README.
- Codecov, coveralls, and gocover all offer ways to create badges for code coverage reports. Another option is to generate a badge as part of a continuous integration process.
## 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;
- 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.
If you are creating a new category, move the projects that apply to the new category, ensuring
that the resulting list has at least 3 projects in every category and that the categories are alphabetized.
Fill out the template in your PR with the links asked for. If you accidentally remove the PR template from the submission, you can find it [here](https://github.com/avelino/awesome-go/blob/main/.github/PULL_REQUEST_TEMPLATE.md).
Then fill out the template in your PR with the links asked for in your README file.
## Congrats, your project got accepted - what now?
You are an awesome project now! Feel encouraged to tell others about it by adding one of these badges:
@ -72,10 +74,10 @@ You are an awesome project now! Feel encouraged to tell others about it by addin
```
## 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.
To prevent removal from awesome-go, your project must maintain the following quality standards.
- Development should be on-going and maintain code quality. Official releases 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 links to quality reports should be to the most recent official release or current ongoing development.
Highly recommended but not required:
- A continuous integration process be part of the ongoing development process
@ -85,21 +87,27 @@ Highly recommended but not required:
## 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:
- Delete the submission template and substitute a description of which criteria the project is not meeting. It should be a combination of the following.
- 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 quality standard links have been removed from the documentation.
- 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)
- 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).
After submitting the PR, create an issue at the project in question linking to the PR and stating the following:
If the project is hosted on Github, include a link to the project's submitter and/or author so
that they will be notified of the desire to remove the project and have an opportunity to respond.
The link should be of the form @githubID.
>It appears that this project is not maintaining the quality standards required to continue to be listed at the Go-Awesome project.
This project is schedule to be removed within 2 weeks of this posting. To continue to be listed at Go-Awesome, please respond at:
If the project is not hosted on Github, open an issue at the project in question's repository linking to the PR
and stating the following:
>This project is currently listed at awesome-go at https://github.com/avelino/awesome-go.
However, it appears that the project is not maintaining the quality standards required to continue to be listed at the awesome-go project.
This project is schedule to be removed within 2 weeks of this posting. To continue to be listed at awesome-go, please respond at:
-- link to above PR --
Then, comment on your PR at Go-Awesome with a link to the removal issue at the project.
Then, comment on your PR at awesome-go with a link to the removal issue at the project.
## Maintainers
@ -120,8 +128,4 @@ Thanks everyone!
## How decision are made
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.
The official group of maintainers has the final decision on what PRs are accepted. Discussions are made openly in issues. Decisions are made by consensus.