|
1 | 1 | # Contribution Guidelines |
2 | 2 |
|
3 | | -## Adding or Updating an Entry |
| 3 | +## Suggest a Project |
4 | 4 |
|
5 | | -Edit [`README_SOURCE.md`](README_SOURCE.md), not the generated `README.md`. |
6 | | - |
7 | | -Add one entry under the appropriate category: |
| 5 | +Edit [`README_SOURCE.md`](README_SOURCE.md), add one line under the best category, |
| 6 | +and open one pull request: |
8 | 7 |
|
9 | 8 | ```markdown |
10 | | -- [Project Name](https://example.com) - A concise description ending with a period. |
| 9 | +- [Project Name](https://github.com/owner/repository) - A concise, neutral description ending with a period. |
11 | 10 | ``` |
12 | 11 |
|
13 | | -Open one pull request per suggestion. The generated README handles alphabetical |
14 | | -ordering, category counts, GitHub stars and repository activity automatically. |
15 | | -Contributors do not need to run the generator. |
16 | | - |
17 | | -Unfortunately, not every library/tool/framework can be considered. This list aims to provide a concise list of noteworthy modern software. This means that suggested software is: |
18 | | - |
19 | | -(a) widely recommended, regardless of personal opinion |
20 | | - |
21 | | -(b) highly discussed in the community due to its innovative nature |
22 | | - |
23 | | -(c) absolutely unique in its approach and function |
24 | | - |
25 | | -(d) a niche product that fills a gap |
26 | | - |
27 | | -Suggested software must be focused on the Java ecosystem. Java should be a primary API, runtime, implementation target or substantial first-class integration. Incidental Java support in an otherwise language-agnostic project is not sufficient. |
28 | | - |
29 | | -Suggested software must also be developer-friendly, which means it meets the following criteria: |
30 | | - |
31 | | -(i) If source code is available, its license is clearly documented. |
| 12 | +Use the canonical GitHub repository when one exists. The generated `README.md` |
| 13 | +handles ordering, counts, stars and activity; contributors do not need to run |
| 14 | +the generator. |
32 | 15 |
|
33 | | -(ii) Any license is acceptable when it is clearly disclosed. Restrictive, noncommercial and source-available licenses must be named in the entry. |
| 16 | +A project should: |
34 | 17 |
|
35 | | -(iii) If commercial, it has clear pricing and at least one free tier. |
| 18 | +- make Java a primary API, runtime, implementation target or substantial |
| 19 | + first-class integration; |
| 20 | +- be noteworthy because it is widely recommended, innovative, unique or fills |
| 21 | + a useful niche; |
| 22 | +- provide English documentation and clearly disclose its license; |
| 23 | +- disclose restrictive, noncommercial or source-available terms in the entry; |
| 24 | +- have clear pricing and a free tier when commercial. |
36 | 25 |
|
37 | | -(iv) It has a documentation in the English language. |
| 26 | +Add `![c]` after the project name for commercial products. Keep descriptions |
| 27 | +short, factual and distinctive from similar entries. Use `Miscellaneous` only |
| 28 | +when no focused category fits. |
38 | 29 |
|
39 | | -## Pull Requests |
| 30 | +Search existing entries and issues before submitting. Self-promotion is |
| 31 | +reviewed carefully but is welcome when the project meets the same criteria. |
| 32 | +Use one pull request per project. |
40 | 33 |
|
41 | | -There are four required criteria for a pull request: |
| 34 | +## Maintainer Notes |
42 | 35 |
|
43 | | -1. If an entry has a similar scope as other entries in the same category, the description must state the unique features that distinguishes it from the other entries. |
| 36 | +Most entries point directly to one GitHub repository. For an umbrella project |
| 37 | +whose Java offering genuinely spans several repositories, keep its public |
| 38 | +homepage and append maintainer-only metadata: |
44 | 39 |
|
45 | | -2. If an entry does not meet conditions _(a)_ to _(d)_ there has to be an explanation either in the description or the pull request why it should be added to the list. |
46 | | - |
47 | | -3. If an entry doesn't fit any of the pre-existing specialized sections, it should go under Miscellaneous. |
48 | | - |
49 | | -4. If two or more entries in Miscellaneous are in the same domain, then they can be moved to a new specialized section. |
50 | | - |
51 | | -Self-promotion is frowned upon and viewed critically, but your suggestion will of course be approved if the criteria match. |
52 | | - |
53 | | -If your entry isn't accepted, please check the [Issues](https://github.com/akullpp/awesome-java/issues) for items marked with the "question" tag to see if it had been previously discussed. If nothing comes up, feel free to create a new issue, adding the "question" tag. |
54 | | - |
55 | | -Furthermore, please ensure your pull request follows the following guidelines: |
56 | | - |
57 | | -- Please search previous suggestions before making a new one, as yours may be a duplicate. |
58 | | -- Please make an individual pull request for each suggestion. |
59 | | -- Use the following format for libraries: \[LIBRARY\]\(LINK\) - DESCRIPTION. |
60 | | -- New categories or improvements to the existing categorization are welcome. |
61 | | -- Keep descriptions short, simple and unbiased. |
62 | | -- End all descriptions with a full stop/period. |
63 | | -- Check your spelling and grammar. |
64 | | -- Make sure your text editor is set to remove trailing whitespace. |
| 40 | +```markdown |
| 41 | +- [Project](https://example.com) - Description. <!-- github: owner/one, owner/two --> |
| 42 | +``` |
65 | 43 |
|
66 | | -Thank you for your suggestions! |
| 44 | +Use at least two canonical repositories. A repository may belong to only one |
| 45 | +entry. The generator sums their stars, uses their most recent push for activity |
| 46 | +and rejects malformed metadata, duplicate repository use and archived |
| 47 | +repositories. |
0 commit comments