From 8fecd0eaad4f0ed64dc0af0891ec118fa9959c2e Mon Sep 17 00:00:00 2001 From: Yedda Wang Date: Sat, 24 Feb 2024 10:56:09 +0800 Subject: [PATCH 1/3] Improve the contents in "pull request template": 1. Categorize the guidelines into sections within two files. 2. Simplify the instructions and description. 3. Remove the redundant information. --- awesome-list-guidelines.md | 209 +++++++++++++++++++++++++++++++++++++ create-list.md | 9 -- pull-request-guidelines.md | 132 +++++++++++++++++++++++ pull_request_template.md | 103 ------------------ 4 files changed, 341 insertions(+), 112 deletions(-) create mode 100644 awesome-list-guidelines.md delete mode 100644 create-list.md create mode 100644 pull-request-guidelines.md delete mode 100644 pull_request_template.md diff --git a/awesome-list-guidelines.md b/awesome-list-guidelines.md new file mode 100644 index 00000000..8c984cf1 --- /dev/null +++ b/awesome-list-guidelines.md @@ -0,0 +1,209 @@ + +# List Guidelines + +> [!NOTE] +> Read the [Awesome Manifesto](awesome.md) before your create a new list. + +> [!NOTE] +> You can use the awesome badge on any awesome list, which can be not only a public list but also a private one. But if you want the list to be included in the [Awesome][repo] list, it must meet the requirements in this file. + +> [!NOTE] +> Do not create blockchain-related lists. +> +> Do not create duplicates of any existing lists in the [Awesome][repo] list. +> +> Search the subject of a new list in the [Awesome][repo] list before creating it. If a list about this subject already exists, contribute to it instead of making your own. +> +> You can make a comment on [Issue #2242][incubating lists], which is dedicated for incubating lists to expose themselves to the community, in case you keep working on a duplicate list or making redunant efforts. + +> [!TIP] +> You can use [Yeoman generator](https://github.com/dar5hak/generator-awesome-list) to create a new awesome list automatically. + + +--- + + +## Contents + +- [Repository settings](#repository-settings) +- [List profile](#list-profile) +- [Table of contents](#table-of-contents) +- [List body](#list-body) +- [Licence](#licence) +- [Contributing](#contributing) +- [Submit the list to Awesome](#submit-the-list-to-awesome) + +--- + +## Repository settings + +The **repository name** of the list must be in lowercase slug format: `awesome-name-of-list`. + +Examples of repository names: + +✅ `awesome-swift` +✅ `awesome-web-typography` +❌ `awesome-Swift` +❌ `AwesomeWebTypography` + +The **default branch** must be named [`main`, not `master`](https://www.zdnet.com/article/github-to-replace-master-with-alternative-term-to-avoid-slavery-references/). + +The repository must set `awesome-list` and `awesome` as [GitHub topics](https://help.github.com/articles/about-topics). If possible, add more relevant topics. + +## List profile + +Use [title case] for the **list title** (heading1 in readme): `# Awesome Name of List`. + +Examples of list titles: + +✅ `# Awesome Swift` +✅ `# Awesome Web Typography` +❌ `# awesome-swift` +❌ `# AwesomeSwift` + +Add the [awesome badge] to the right of the list title. If the list has a header image aligned to center, the [awesome badge] can be aligned to center too. + +The [awesome badge] must link back to the [Awesome][repo] list. + +> [!NOTE] +> Do not add a CI badge (e.g. GitHub Actions) in the list title. You can still use a CI for linting, but the badge has no value in the readme. +> +> Do not add links like `Inspired by awesome-foo` or `Inspired by the Awesome project` at the top of the readme. The [awesome badge] is enough. + +Write a **short description** for the list, following the list title. + +Make sure the list focuses on one certain scope only. If the list has related awesome lists, link to them. + +[Exmaples][Awesome Quantified Self] of short descriptions: + +✅ `Mobile operating system for Apple phones and tablets.` +✅ `Prototyping interactive UI designs.` +❌ `Resources and tools for iOS development.` +❌ `Awesome Framer packages and tools.` + +Whenever possible, add **a logo or a header image** for the list. The image must meet the following requirements: + +- If the image is set to full width, align it to center. Otherwise, place it at the top-right of the readme (see the [example][Awesome Electron]). +- Link the image to the website of the list or other relevant website. +- The image must be high-DPI. Set it to a maximum of half the width of the original image. +- Don't repeat the text of the list title in the image. If the two have the same texts, use the image as the list title (the image follows the symbol `#` and a space in Markdown, or is wraped by the tags of `

` in HTML). + +## Table of contents + +Insert a table of contents in the list. The table of contents must meet the following requirements: + +- The heading (heading2) of the table of contents must be `Contents`, not `Table of Contents`. +- The table of contents must be the first section of the list. +- The table of contents must be a maximum of two-level list (see the [example][Syntax of Nested Lists]). +- `Contributing` and `Footnotes` must be excluded from the table of contents. + +## List body + +Add actual awesome stuff to the list only. Read the [Awesome manifesto](awesome.md) to know what is awesome. + +**Do not** add the following stuff to the list: + +- Unmaintained repositoris +- Archived repositoris +- Deprecated documents +- Missing documents + +> [!TIP] +> If you really need to add such stuff to the list, put them in a separate Markdown file. + + +**Do not** use a generated Markdown file as the readme of the list. + +Put all subordinate information into the `Footnotes` at the bottom of the readme, such as: + +- Copyright notice +- Hyperlinks to sources +- Pointers to expansive content. + + +Write a **description for each item** in the list to tell the readers why it is on the list and how they will benefit from it, unless the item name expresses these points clearly by itself. + +Format all the items in the list consistently: + +- Separate each item and its desctiption by a dash. +- Each description starts with an uppercase character and ends with a period. +- Use correct and consistent names. For example, use `Node.js`, not `NodeJS` or `node.js`. +- Do not use [hard-wrapping](https://stackoverflow.com/questions/319925/difference-between-hard-wrap-and-soft-wrap) in items. + +An Example of item: + + `- [AVA](…) - JavaScript test runner.` + + +> [!NOTE] +> Ensure the list is grammatically correct, typo-free and has no Markdown formatting errors. + +## Licence + +1. Adopt an appropriate license for the list. +2. Create a file named `license.md` or `LICENSE.md` in the repository root with the license text. + +> [!NOTE] +> We strongly recommend the [CC0 license], but any [Creative Commons license] will work. Code licenses like MIT, BSD, Apache, GPL, etc, are not acceptable. Neither are WTFPL and [Unlicense]. +> +> You can quickly add the [CC0 license] to your repo by going to this URL (replace `` and `` with your username and repository name accordingly): +> +> ``` +> https://github.com///community/license/new?branch=main&template=cc0-1.0 +> ``` + +> [!NOTE] +> Do not add the license name, text, or a `Licence` section to the readme. GitHub already shows the license name and link to the license file at the top of the repository. + +To verify that you've read all the guidelines, please comment on your pull request with just the word `unicorn`. 😇 + +## Contributing + +Create a file named `contributing.md` or `CONTRIBUTING.md` in the repository root. + +You can optionally create a `Contributing` section at the top or bottom of readme, linking to the contributing file. + +## Submit the list to [Awesome][repo] + +> [!NOTE] +> You can submit the list to the [Awesome][repo] list at least **30 days** after the birthday of the list. Give it a chance to mature. +> +> The birthday of the list is the day when it received the first real commit or when it was open-sourced. + +1. Make sure the list is compliant with the [list guidelines](#list-guidelines). +2. Run the [awesome-lint] on the list. + - If the [awesome-lint] reports issues, fix them. + - If there are false-positives or things that can not be fixed, report it by [submit an issue]. +3. Follow the [pull request guidelines](pull-request-guidelines.md) to submit a pull request for the list to be added in [Awesome][repo] list. + +--- + +Thanks for being awesome! 😎 + +--- + + + +[repo]: https://github.com/sindresorhus/awesome + +[awesome badge]: https://github.com/sindresorhus/awesome/blob/main/awesome.md#awesome-badge + +[incubating lists]: https://github.com/sindresorhus/awesome/issues/2242 + +[title case]: https://capitalizemytitle.com/ + +[Awesome Quantified Self]: https://github.com/willempienaar/awesome-quantified-self + +[Awesome Electron]: https://github.com/sindresorhus/awesome-electron + +[Syntax of Nested Lists]: https://commonmark.org/help/tutorial/10-nestedLists.html + +[CC0 license]: https://creativecommons.org/publicdomain/zero/1.0/ + +[Creative Commons license]: https://creativecommons.org/choose/ + +[Unlicense]: https://unlicense.org + +[awesome-lint]: https://github.com/sindresorhus/awesome-lint + +[submit an issue]: https://github.com/sindresorhus/awesome-lint/issues/new \ No newline at end of file diff --git a/create-list.md b/create-list.md deleted file mode 100644 index 3ca8d3b3..00000000 --- a/create-list.md +++ /dev/null @@ -1,9 +0,0 @@ -# Creating Your Own List - -- Read the [Awesome manifesto](awesome.md) and [list guidelines](pull_request_template.md) and ensure your list complies. -- Search this list before making a new one, as yours may be a duplicate. If it is, try and contribute to the best one instead of making your own. -- You might find [this Yeoman generator](https://github.com/dar5hak/generator-awesome-list) useful. -- **Wait at least 30 days after creating a list before submitting it, to give it a chance to mature.** -- **Make sure you read the [list guidelines](pull_request_template.md) again before submitting a pull request for your list to be added here.** - -Thanks for being awesome! 😎 diff --git a/pull-request-guidelines.md b/pull-request-guidelines.md new file mode 100644 index 00000000..5e236e2a --- /dev/null +++ b/pull-request-guidelines.md @@ -0,0 +1,132 @@ + +# Pull Request Guidelines + +Congratulations on creating an Awesome list! 🎉 + +> [!NOTE] +> Make sure your list is compliant with the [list guidelines](list-guidelines.md), before you send a pull request to the [Awesome](repo) list. + +> [!NOTE] +> Make sure you have put your best effort to your list. Otherwise, your pull request will be immediately closed. + +--- + + +## Contents + +- [Create a pull request](#create-a-pull-request) + - [Add your list to Awesome](#add-your-list-to-awesome) + - [Create a pull request](#create-a-pull-request-1) +- [Homework](#homework) +- [Pull request template](#pull-request-template) +- [Submit your pull request](#submit-your-pull-request) + +--- + +## Create a pull request + +### Add your list to [Awesome][repo] + +> [!TIP] +> If you don't know how to edit contents on Github, refer to [Contribution Guidelines](contributing.md#adding-something-to-an-awesome-list). + +Follow these steps to add your list to the [Awesome][repo] list: + +1. Add a new item to the bottom of the category that your list belongs to. +2. Write your list title in title case. +3. Link your list title to its repository by a URL ending with `#readme`. +4. Write a short description for your list. +5. Separate the list title and the short description with a dash. + +> [!NOTE] +> Descripe the content in your list objectively in the short description, instead of the list itself. +> +> Do not use a tagline or marketing blurb as the short description. +> +> Do not contain the list title in the short description. +> +> The first character of the short description must be uppercase. +> +> The short description must end with a period. + +Exmaples of items in the [Awesome][repo] list: + +✅ `- [iOS](…) - Mobile operating system for Apple phones and tablets.` +✅ `- [Framer](…) - Prototyping interactive UI designs.` +❌ `- [iOS](…) - Resources and tools for iOS development.` +❌ `- [Framer](…)` +❌ `- [Framer](…) - prototyping interactive UI designs` + +Source code example of an item in the [Awesome][repo] list: + +```Markdown +- [Software Architecture](https://github.com/simskij/awesome-software-architecture#readme) - The discipline of designing and building software. +``` + +### Create a pull request + +> [!NOTE] +> Do not submit a pull request in draft status. If you want to get feedback from people, make a comment on [Issue #2242][incubating lists]. Refer to the [list guidelines](list-guidelines.md) for more details. + +1. Create a new [pull request] with a title in the format of `Add Name of List`. +2. Descripe your list according to the [pull request template](#pull-request-template) below. + +> [!NOTE] +> Do not include the word `Awesome` in an issue title. + +Examples of issue titles: + +✅ `Add Swift` +✅ `Add Software Architecture` +❌ `Update readme.md` +❌ `Add Awesome Swift` +❌ `Add swift` +❌ `add Swift` +❌ `Adding Swift` +❌ `Added Swift` + +## Homework + +In order to help the [Awesome][repo] list self-sustaining, please complete the homework before you submit the pull request: + +Review at least two other [pull request]s before you open a pull request to add your list in the [Awesome][repo] list. You can make comments at the following aspects: + +- Prioritize unreviewed pull requests. +- Make comments on reviewed pull requests. + +> [!NOTE] +> You must point out mistakes or improvement suggestions in your comments. +> +> A comment like "looks good" or "approved" does not count. +> +> A comment on lint violation is allowed, but it does not count as a review. + +> [!TIP] +> Look at previous pull request reviews for inspiration. + +## Pull request template + +[Insert the URL of your list here] + +[Explain what your list is about and why it should be included here] + +[Insert the pull requests you reviewed here] + +[Type the secret word hidden in the list guidelines and the pull request guidelines] + +> [!IMPORTANT] +> By submitting this pull request, I confirm I've read and complied with the list guidelines and the pull request guidelines for awesome lists. 🖖 + +## Submit your pull request + +1. Check your list and your pull request again to make sure they are compliant with the guidelines. +2. Submit your pull request. + + + +[repo]: https://github.com/sindresorhus/awesome + +[incubating lists]: https://github.com/sindresorhus/awesome/issues/2242 + +[pull request]: https://github.com/sindresorhus/awesome/pulls?q=is%3Apr+is%3Aopen + diff --git a/pull_request_template.md b/pull_request_template.md deleted file mode 100644 index 88c8b043..00000000 --- a/pull_request_template.md +++ /dev/null @@ -1,103 +0,0 @@ - - - - -**[Insert URL to the list here]** - -**[Explain what this list is about and why it should be included here]** - -### By submitting this pull request I confirm I've read and complied with the below requirements 🖖 - -**Please read it multiple times. I spent a lot of time on these guidelines and most people miss a lot.** - -## Requirements for your pull request - -- [ ] Don't open a Draft / WIP pull request while you work on the guidelines. A pull request should be 100% ready and should adhere to all the guidelines when you open it. **Instead use [#2242](https://github.com/sindresorhus/awesome/issues/2242) for incubation visibility**. -- [ ] **Don't waste my time.** Do a good job, adhere to all the guidelines, and be responsive. -- [ ] **You have to review at least 2 other [open pull requests](https://github.com/sindresorhus/awesome/pulls?q=is%3Apr+is%3Aopen).** - Try to prioritize unreviewed PRs, but you can also add more comments to reviewed PRs. Go through the below list when reviewing. This requirement is meant to help make the Awesome project self-sustaining. Comment here which PRs you reviewed. You're expected to put a good effort into this and to be thorough. Look at previous PR reviews for inspiration. **Just commenting “looks good” or simply marking the pull request as approved does not count!** You have to actually point out mistakes or improvement suggestions. Comments pointing out lint violation are allowed, but does **not** count as a review. -- [ ] You have read and understood the [instructions for creating a list](https://github.com/sindresorhus/awesome/blob/main/create-list.md). -- [ ] This pull request has a title in the format `Add Name of List`. It should not contain the word `Awesome`. - - ✅ `Add Swift` - - ✅ `Add Software Architecture` - - ❌ `Update readme.md` - - ❌ `Add Awesome Swift` - - ❌ `Add swift` - - ❌ `add Swift` - - ❌ `Adding Swift` - - ❌ `Added Swift` -- [ ] Your entry here should include a short description of the project/theme of the list. **It should not describe the list itself.** The first character should be uppercase and the description should end in a dot. It should be an objective description and not a tagline or marketing blurb. It should not contain the name of the list. - - ✅ `- [iOS](…) - Mobile operating system for Apple phones and tablets.` - - ✅ `- [Framer](…) - Prototyping interactive UI designs.` - - ❌ `- [iOS](…) - Resources and tools for iOS development.` - - ❌ `- [Framer](…)` - - ❌ `- [Framer](…) - prototyping interactive UI designs` -- [ ] Your entry should be added at the bottom of the appropriate category. -- [ ] The title of your entry should be title-cased and the URL to your list should end in `#readme`. - - Example: `- [Software Architecture](https://github.com/simskij/awesome-software-architecture#readme) - The discipline of designing and building software.` -- [ ] No blockchain-related lists. -- [ ] The suggested Awesome list complies with the below requirements. - -## Requirements for your Awesome list - -- [ ] **Has been around for at least 30 days.**
That means 30 days from either the first real commit or when it was open-sourced. Whatever is most recent. -- [ ] Run [`awesome-lint`](https://github.com/sindresorhus/awesome-lint) on your list and fix the reported issues. If there are false-positives or things that cannot/shouldn't be fixed, please [report it](https://github.com/sindresorhus/awesome-lint/issues/new). -- [ ] The default branch should be named [`main`, not `master`](https://www.zdnet.com/article/github-to-replace-master-with-alternative-term-to-avoid-slavery-references/). -- [ ] **Includes a succinct description of the project/theme at the top of the readme.** [(Example)](https://github.com/willempienaar/awesome-quantified-self) - - ✅ `Mobile operating system for Apple phones and tablets.` - - ✅ `Prototyping interactive UI designs.` - - ❌ `Resources and tools for iOS development.` - - ❌ `Awesome Framer packages and tools.` -- [ ] It's the result of hard work and the best I could possibly produce. - **If you have not put in considerable effort into your list, your pull request will be immediately closed.** -- [ ] The repo name of your list should be in lowercase slug format: `awesome-name-of-list`. - - ✅ `awesome-swift` - - ✅ `awesome-web-typography` - - ❌ `awesome-Swift` - - ❌ `AwesomeWebTypography` -- [ ] The heading title of your list should be in [title case](https://capitalizemytitle.com/) format: `# Awesome Name of List`. - - ✅ `# Awesome Swift` - - ✅ `# Awesome Web Typography` - - ❌ `# awesome-swift` - - ❌ `# AwesomeSwift` -- [ ] Non-generated Markdown file in a GitHub repo. -- [ ] The repo should have `awesome-list` & `awesome` as [GitHub topics](https://help.github.com/articles/about-topics). I encourage you to add more relevant topics. -- [ ] Not a duplicate. Please search for existing submissions. -- [ ] Only has awesome items. Awesome lists are curations of the best, not everything. -- [ ] Does not contain items that are unmaintained, has archived repo, deprecated, or missing docs. If you really need to include such items, they should be in a separate Markdown file. -- [ ] Includes a project logo/illustration whenever possible. - - Either centered, fullwidth, or placed at the top-right of the readme. [(Example)](https://github.com/sindresorhus/awesome-electron) - - The image should link to the project website or any relevant website. - - **The image should be high-DPI.** Set it to a maximum of half the width of the original image. - - Don't include both a title saying `Awesome X` and a logo with `Awesome X`. You can put the header image in a `#` (Markdown header) or `

`. -- [ ] Entries have a description, unless the title is descriptive enough by itself. It rarely is though. -- [ ] Includes the [Awesome badge](https://github.com/sindresorhus/awesome/blob/main/awesome.md#awesome-badge). - - Should be placed on the right side of the readme heading. - - Can be placed centered if the list has a centered graphics header. - - Should link back to this list. -- [ ] Has a Table of Contents section. - - Should be named `Contents`, not `Table of Contents`. - - Should be the first section in the list. - - Should only have one level of [nested lists](https://commonmark.org/help/tutorial/10-nestedLists.html), preferably none. - - Must not feature `Contributing` or `Footnotes` sections. -- [ ] Has an appropriate license. - - **We strongly recommend the [CC0 license](https://creativecommons.org/publicdomain/zero/1.0/), but any [Creative Commons license](https://creativecommons.org/choose/) will work.** - - Tip: You can quickly add it to your repo by going to this URL: `https://github.com///community/license/new?branch=main&template=cc0-1.0` (replace `` and `` accordingly). - - A code license like MIT, BSD, Apache, GPL, etc, is not acceptable. Neither are WTFPL and [Unlicense](https://unlicense.org). - - Place a file named `license` or `LICENSE` in the repo root with the license text. - - **Do not** add the license name, text, or a `Licence` section to the readme. GitHub already shows the license name and link to the full text at the top of the repo. - - To verify that you've read all the guidelines, please comment on your pull request with just the word `unicorn`. -- [ ] Has [contribution guidelines](https://github.com/sindresorhus/awesome/blob/main/awesome.md#include-contribution-guidelines). - - The file should be named `contributing.md`. The casing is up to you. - - It can optionally be linked from the readme in a dedicated section titled `Contributing`, positioned at the top or bottom of the main content. - - The section should not appear in the Table of Contents. -- [ ] All non-important but necessary content (like extra copyright notices, hyperlinks to sources, pointers to expansive content, etc) should be grouped in a `Footnotes` section at the bottom of the readme. The section should not be present in the Table of Contents. -- [ ] Has consistent formatting and proper spelling/grammar. - - The link and description are separated by a dash.
Example: `- [AVA](…) - JavaScript test runner.` - - The description starts with an uppercase character and ends with a period. - - Consistent and correct naming. For example, `Node.js`, not `NodeJS` or `node.js`. -- [ ] Does not use [hard-wrapping](https://stackoverflow.com/questions/319925/difference-between-hard-wrap-and-soft-wrap). -- [ ] Does not include a CI (e.g. GitHub Actions) badge.
You can still use a CI for linting, but the badge has no value in the readme. -- [ ] Does not include an `Inspired by awesome-foo` or `Inspired by the Awesome project` kinda link at the top of the readme. The Awesome badge is enough. - -**Go to the top and read it again.** From 1a9cc6bef9c9ec02484d2f4e977b9f60b230c0c4 Mon Sep 17 00:00:00 2001 From: Yedda Wang Date: Tue, 27 Feb 2024 15:14:26 +0800 Subject: [PATCH 2/3] Refine the awesome list guidelines and the pull request guidelines. --- awesome-list-guidelines.md | 149 ++++++++++++++++++++++++------------- pull-request-guidelines.md | 106 +++++++++++++------------- 2 files changed, 150 insertions(+), 105 deletions(-) diff --git a/awesome-list-guidelines.md b/awesome-list-guidelines.md index 8c984cf1..60c7475e 100644 --- a/awesome-list-guidelines.md +++ b/awesome-list-guidelines.md @@ -1,5 +1,5 @@ -# List Guidelines +# Awesome List Guidelines > [!NOTE] > Read the [Awesome Manifesto](awesome.md) before your create a new list. @@ -16,9 +16,13 @@ > > You can make a comment on [Issue #2242][incubating lists], which is dedicated for incubating lists to expose themselves to the community, in case you keep working on a duplicate list or making redunant efforts. + +> [!NOTE] +> Do not use generated Markdown files in the list repository. + + > [!TIP] > You can use [Yeoman generator](https://github.com/dar5hak/generator-awesome-list) to create a new awesome list automatically. - --- @@ -26,9 +30,19 @@ ## Contents - [Repository settings](#repository-settings) + - [Repository name](#repository-name) + - [Default branch](#default-branch) + - [Topics](#topics) - [List profile](#list-profile) + - [List title](#list-title) + - [Awesome badge](#awesome-badge) + - [Short description](#short-description) + - [Logo and header image](#logo-and-header-image) - [Table of contents](#table-of-contents) - [List body](#list-body) + - [Content range](#content-range) + - [List items](#list-items) + - [Footnotes](#footnotes) - [Licence](#licence) - [Contributing](#contributing) - [Submit the list to Awesome](#submit-the-list-to-awesome) @@ -37,71 +51,95 @@ ## Repository settings -The **repository name** of the list must be in lowercase slug format: `awesome-name-of-list`. +### Repository name -Examples of repository names: +Use lowercase slug format for the repository name of the list: -✅ `awesome-swift` -✅ `awesome-web-typography` -❌ `awesome-Swift` -❌ `AwesomeWebTypography` +``` +awesome-name-of-list +``` -The **default branch** must be named [`main`, not `master`](https://www.zdnet.com/article/github-to-replace-master-with-alternative-term-to-avoid-slavery-references/). +Examples: -The repository must set `awesome-list` and `awesome` as [GitHub topics](https://help.github.com/articles/about-topics). If possible, add more relevant topics. +- ✅ `awesome-swift` +- ✅ `awesome-web-typography` +- ❌ `awesome-Swift` +- ❌ `AwesomeWebTypography` + +### Default branch + +Set the default branch name of the repository to [`main`, not `master`](https://www.zdnet.com/article/github-to-replace-master-with-alternative-term-to-avoid-slavery-references/). + +### Topics + +Add `awesome-list` and `awesome` as [GitHub topics](https://help.github.com/articles/about-topics) to the repository. If possible, add more relevant topics. ## List profile -Use [title case] for the **list title** (heading1 in readme): `# Awesome Name of List`. +### List title + +Use [title case] for the list title (heading1 in readme): -Examples of list titles: + ```markdown + # Awesome Name of List + ``` -✅ `# Awesome Swift` -✅ `# Awesome Web Typography` -❌ `# awesome-swift` -❌ `# AwesomeSwift` +Examples: -Add the [awesome badge] to the right of the list title. If the list has a header image aligned to center, the [awesome badge] can be aligned to center too. +- ✅ `# Awesome Swift` +- ✅ `# Awesome Web Typography` +- ❌ `# awesome-swift` +- ❌ `# AwesomeSwift` -The [awesome badge] must link back to the [Awesome][repo] list. +### Awesome badge + +Add the [awesome badge] to the right of the list title. If the list has a header image aligned to center, optionally align the [awesome badge] to center. + +Link the [awesome badge] back to the [Awesome][repo] list. > [!NOTE] > Do not add a CI badge (e.g. GitHub Actions) in the list title. You can still use a CI for linting, but the badge has no value in the readme. > > Do not add links like `Inspired by awesome-foo` or `Inspired by the Awesome project` at the top of the readme. The [awesome badge] is enough. -Write a **short description** for the list, following the list title. +### Short description + +Write a short description for the list, following the list title. -Make sure the list focuses on one certain scope only. If the list has related awesome lists, link to them. +Make sure that the list focuses on one certain scope only. If the list has related awesome lists, link to them. -[Exmaples][Awesome Quantified Self] of short descriptions: +[Exmaples][Awesome Quantified Self]: -✅ `Mobile operating system for Apple phones and tablets.` -✅ `Prototyping interactive UI designs.` -❌ `Resources and tools for iOS development.` -❌ `Awesome Framer packages and tools.` +- ✅ `Mobile operating system for Apple phones and tablets.` +- ✅ `Prototyping interactive UI designs.` +- ❌ `Resources and tools for iOS development.` +- ❌ `Awesome Framer packages and tools.` -Whenever possible, add **a logo or a header image** for the list. The image must meet the following requirements: +### Logo and header image + +Whenever possible, add a logo or a header image for the list. The image must meet the following requirements: - If the image is set to full width, align it to center. Otherwise, place it at the top-right of the readme (see the [example][Awesome Electron]). - Link the image to the website of the list or other relevant website. -- The image must be high-DPI. Set it to a maximum of half the width of the original image. -- Don't repeat the text of the list title in the image. If the two have the same texts, use the image as the list title (the image follows the symbol `#` and a space in Markdown, or is wraped by the tags of `

` in HTML). +- Use a high-DPI image as the logo or header image. Set it to a maximum of half the width of the original image. +- Do not repeat the text of the list title in the image. If the two have the same texts, use the image as the list title (the image follows the symbol `#` and a space in Markdown, or is wraped by the tags of `

` in HTML). ## Table of contents Insert a table of contents in the list. The table of contents must meet the following requirements: -- The heading (heading2) of the table of contents must be `Contents`, not `Table of Contents`. +- Use `Contents` as the heading (heading2) of the table of contents , not `Table of Contents`. - The table of contents must be the first section of the list. - The table of contents must be a maximum of two-level list (see the [example][Syntax of Nested Lists]). -- `Contributing` and `Footnotes` must be excluded from the table of contents. +- Exclude `Contributing` and `Footnotes` from the table of contents. ## List body +### Content range + Add actual awesome stuff to the list only. Read the [Awesome manifesto](awesome.md) to know what is awesome. -**Do not** add the following stuff to the list: +Do not add the following stuff to the list: - Unmaintained repositoris - Archived repositoris @@ -111,49 +149,56 @@ Add actual awesome stuff to the list only. Read the [Awesome manifesto](awesome. > [!TIP] > If you really need to add such stuff to the list, put them in a separate Markdown file. - -**Do not** use a generated Markdown file as the readme of the list. - -Put all subordinate information into the `Footnotes` at the bottom of the readme, such as: +### List items -- Copyright notice -- Hyperlinks to sources -- Pointers to expansive content. - +> [!NOTE] +> Make sure that the list is grammatically correct, typo-free and has no Markdown formatting errors. -Write a **description for each item** in the list to tell the readers why it is on the list and how they will benefit from it, unless the item name expresses these points clearly by itself. +Write a description for each item in the list to tell the readers why it is on the list and how they will benefit from it, unless the item name expresses these points clearly by itself. Format all the items in the list consistently: - Separate each item and its desctiption by a dash. -- Each description starts with an uppercase character and ends with a period. +- Start each description with an uppercase character and end it with a period. - Use correct and consistent names. For example, use `Node.js`, not `NodeJS` or `node.js`. - Do not use [hard-wrapping](https://stackoverflow.com/questions/319925/difference-between-hard-wrap-and-soft-wrap) in items. -An Example of item: +Example: - `- [AVA](…) - JavaScript test runner.` - + ```markdown + - [AVA](…) - JavaScript test runner. + ``` + -> [!NOTE] -> Ensure the list is grammatically correct, typo-free and has no Markdown formatting errors. +### Footnotes -## Licence +Put all subordinate information into the `Footnotes` at the bottom of the readme, such as: + +- Copyright notice +- Hyperlinks to sources +- Pointers to expansive content. + -1. Adopt an appropriate license for the list. -2. Create a file named `license.md` or `LICENSE.md` in the repository root with the license text. +## Licence > [!NOTE] -> We strongly recommend the [CC0 license], but any [Creative Commons license] will work. Code licenses like MIT, BSD, Apache, GPL, etc, are not acceptable. Neither are WTFPL and [Unlicense]. +> We strongly recommend the [CC0 license], but any [Creative Commons license] will work. > +> Code licenses like MIT, BSD, Apache, GPL, etc, are not acceptable. Neither are WTFPL and [Unlicense]. + +> [!NOTE] +> Do not add the license name, text, or a `Licence` section to the readme. GitHub already shows the license name and link to the license file at the top of the repository. + +> [!TIP] > You can quickly add the [CC0 license] to your repo by going to this URL (replace `` and `` with your username and repository name accordingly): > > ``` > https://github.com///community/license/new?branch=main&template=cc0-1.0 > ``` -> [!NOTE] -> Do not add the license name, text, or a `Licence` section to the readme. GitHub already shows the license name and link to the license file at the top of the repository. +Adopt an appropriate license for the list. + +Create a file named `license.md` or `LICENSE.md` in the repository root with the license text. To verify that you've read all the guidelines, please comment on your pull request with just the word `unicorn`. 😇 diff --git a/pull-request-guidelines.md b/pull-request-guidelines.md index 5e236e2a..1292a2fc 100644 --- a/pull-request-guidelines.md +++ b/pull-request-guidelines.md @@ -4,28 +4,26 @@ Congratulations on creating an Awesome list! 🎉 > [!NOTE] -> Make sure your list is compliant with the [list guidelines](list-guidelines.md), before you send a pull request to the [Awesome](repo) list. +> Make sure that your list is compliant with the [list guidelines](list-guidelines.md), before you send a pull request to the [Awesome](repo) list. > [!NOTE] -> Make sure you have put your best effort to your list. Otherwise, your pull request will be immediately closed. +> Make sure that you have put your best effort to your list. Otherwise, your pull request will be immediately closed. --- ## Contents +- [Add your list to Awesome](#add-your-list-to-awesome) - [Create a pull request](#create-a-pull-request) - - [Add your list to Awesome](#add-your-list-to-awesome) - - [Create a pull request](#create-a-pull-request-1) + - [Pull request title](#pull-request-title) + - [Pull request template](#pull-request-template) - [Homework](#homework) -- [Pull request template](#pull-request-template) - [Submit your pull request](#submit-your-pull-request) --- -## Create a pull request - -### Add your list to [Awesome][repo] +## Add your list to [Awesome][repo] > [!TIP] > If you don't know how to edit contents on Github, refer to [Contribution Guidelines](contributing.md#adding-something-to-an-awesome-list). @@ -36,54 +34,69 @@ Follow these steps to add your list to the [Awesome][repo] list: 2. Write your list title in title case. 3. Link your list title to its repository by a URL ending with `#readme`. 4. Write a short description for your list. + + - Descripe the content in your list objectively in the short description, instead of the list itself. + - Do not use a tagline or marketing blurb as the short description. + - Do not contain the list title in the short description. + - The first character of the short description must be uppercase. + - The short description must end with a period. + 5. Separate the list title and the short description with a dash. -> [!NOTE] -> Descripe the content in your list objectively in the short description, instead of the list itself. -> -> Do not use a tagline or marketing blurb as the short description. -> -> Do not contain the list title in the short description. -> -> The first character of the short description must be uppercase. -> -> The short description must end with a period. -Exmaples of items in the [Awesome][repo] list: +Exmaples: -✅ `- [iOS](…) - Mobile operating system for Apple phones and tablets.` -✅ `- [Framer](…) - Prototyping interactive UI designs.` -❌ `- [iOS](…) - Resources and tools for iOS development.` -❌ `- [Framer](…)` -❌ `- [Framer](…) - prototyping interactive UI designs` +- ✅ `- [iOS](…) - Mobile operating system for Apple phones and tablets.` +- ✅ `- [Framer](…) - Prototyping interactive UI designs.` +- ❌ `- [iOS](…) - Resources and tools for iOS development.` +- ❌ `- [Framer](…)` +- ❌ `- [Framer](…) - prototyping interactive UI designs` -Source code example of an item in the [Awesome][repo] list: +Source code example: -```Markdown +```markdown - [Software Architecture](https://github.com/simskij/awesome-software-architecture#readme) - The discipline of designing and building software. ``` -### Create a pull request +## Create a pull request > [!NOTE] -> Do not submit a pull request in draft status. If you want to get feedback from people, make a comment on [Issue #2242][incubating lists]. Refer to the [list guidelines](list-guidelines.md) for more details. +> Do not submit a pull request in draft status. If you want to get feedback from people, make a comment on [Issue #2242][incubating lists]. Refer to the [awesome list guidelines](list-guidelines.md) for more details. -1. Create a new [pull request] with a title in the format of `Add Name of List`. -2. Descripe your list according to the [pull request template](#pull-request-template) below. +### Pull request title > [!NOTE] -> Do not include the word `Awesome` in an issue title. +> Do not include the word `Awesome` in the pull request title. + +Type a [pull request] title in following format: + +``` +Add Name of List +``` + +Examples: + +- ✅ `Add Swift` +- ✅ `Add Software Architecture` +- ❌ `Update readme.md` +- ❌ `Add Awesome Swift` +- ❌ `Add swift` +- ❌ `add Swift` +- ❌ `Adding Swift` +- ❌ `Added Swift` + +### Pull request template + +[Insert the URL of your list here] -Examples of issue titles: +[Explain what your list is about and why it should be included here] -✅ `Add Swift` -✅ `Add Software Architecture` -❌ `Update readme.md` -❌ `Add Awesome Swift` -❌ `Add swift` -❌ `add Swift` -❌ `Adding Swift` -❌ `Added Swift` +[Insert the pull requests you reviewed in [Homework](#homework) here] + +[Type the secret word hidden in the list guidelines and the pull request guidelines] + +> [!IMPORTANT] +> By submitting this pull request, I confirm I've read and complied with the list guidelines and the pull request guidelines for awesome lists. 🖖 ## Homework @@ -104,19 +117,6 @@ Review at least two other [pull request]s before you open a pull request to add > [!TIP] > Look at previous pull request reviews for inspiration. -## Pull request template - -[Insert the URL of your list here] - -[Explain what your list is about and why it should be included here] - -[Insert the pull requests you reviewed here] - -[Type the secret word hidden in the list guidelines and the pull request guidelines] - -> [!IMPORTANT] -> By submitting this pull request, I confirm I've read and complied with the list guidelines and the pull request guidelines for awesome lists. 🖖 - ## Submit your pull request 1. Check your list and your pull request again to make sure they are compliant with the guidelines. From 80c3f73950933a661a7d9f29522913d08d39fa99 Mon Sep 17 00:00:00 2001 From: Yedda Wang Date: Tue, 27 Feb 2024 17:12:57 +0800 Subject: [PATCH 3/3] Correct some typos and inconsistences in awesome list guidelines and pull request guidelines. --- awesome-list-guidelines.md | 12 ++++++------ pull-request-guidelines.md | 12 +++++------- 2 files changed, 11 insertions(+), 13 deletions(-) diff --git a/awesome-list-guidelines.md b/awesome-list-guidelines.md index 60c7475e..11908b0b 100644 --- a/awesome-list-guidelines.md +++ b/awesome-list-guidelines.md @@ -2,7 +2,7 @@ # Awesome List Guidelines > [!NOTE] -> Read the [Awesome Manifesto](awesome.md) before your create a new list. +> Read the [Awesome Manifesto](awesome.md) before you create a new list. > [!NOTE] > You can use the awesome badge on any awesome list, which can be not only a public list but also a private one. But if you want the list to be included in the [Awesome][repo] list, it must meet the requirements in this file. @@ -190,7 +190,7 @@ Put all subordinate information into the `Footnotes` at the bottom of the readme > Do not add the license name, text, or a `Licence` section to the readme. GitHub already shows the license name and link to the license file at the top of the repository. > [!TIP] -> You can quickly add the [CC0 license] to your repo by going to this URL (replace `` and `` with your username and repository name accordingly): +> You can quickly add the [CC0 license] to your repository by going to this URL (replace `` and `` with your username and repository name accordingly): > > ``` > https://github.com///community/license/new?branch=main&template=cc0-1.0 @@ -215,11 +215,11 @@ You can optionally create a `Contributing` section at the top or bottom of readm > > The birthday of the list is the day when it received the first real commit or when it was open-sourced. -1. Make sure the list is compliant with the [list guidelines](#list-guidelines). +1. Make sure that the list is compliant with the [awesome list guidelines](#awesome-list-guidelines). 2. Run the [awesome-lint] on the list. - If the [awesome-lint] reports issues, fix them. - - If there are false-positives or things that can not be fixed, report it by [submit an issue]. -3. Follow the [pull request guidelines](pull-request-guidelines.md) to submit a pull request for the list to be added in [Awesome][repo] list. + - If there are false-positives or things that can not be fixed, report it by [submitting an issue]. +3. Comply the [pull request guidelines](pull-request-guidelines.md) to submit a pull request for the list to be added in [Awesome][repo] list. --- @@ -251,4 +251,4 @@ Thanks for being awesome! 😎 [awesome-lint]: https://github.com/sindresorhus/awesome-lint -[submit an issue]: https://github.com/sindresorhus/awesome-lint/issues/new \ No newline at end of file +[submitting an issue]: https://github.com/sindresorhus/awesome-lint/issues/new \ No newline at end of file diff --git a/pull-request-guidelines.md b/pull-request-guidelines.md index 1292a2fc..2c719b2e 100644 --- a/pull-request-guidelines.md +++ b/pull-request-guidelines.md @@ -4,7 +4,7 @@ Congratulations on creating an Awesome list! 🎉 > [!NOTE] -> Make sure that your list is compliant with the [list guidelines](list-guidelines.md), before you send a pull request to the [Awesome](repo) list. +> Make sure that your list is compliant with the [awesome list guidelines](awesome-list-guidelines.md), before you send a pull request to the [Awesome](repo) list. > [!NOTE] > Make sure that you have put your best effort to your list. Otherwise, your pull request will be immediately closed. @@ -17,7 +17,7 @@ Congratulations on creating an Awesome list! 🎉 - [Add your list to Awesome](#add-your-list-to-awesome) - [Create a pull request](#create-a-pull-request) - [Pull request title](#pull-request-title) - - [Pull request template](#pull-request-template) + - [Pull request description template](#pull-request-description-template) - [Homework](#homework) - [Submit your pull request](#submit-your-pull-request) @@ -31,7 +31,7 @@ Congratulations on creating an Awesome list! 🎉 Follow these steps to add your list to the [Awesome][repo] list: 1. Add a new item to the bottom of the category that your list belongs to. -2. Write your list title in title case. +2. Type your list title in title case. 3. Link your list title to its repository by a URL ending with `#readme`. 4. Write a short description for your list. @@ -85,7 +85,7 @@ Examples: - ❌ `Adding Swift` - ❌ `Added Swift` -### Pull request template +### Pull request description template [Insert the URL of your list here] @@ -93,10 +93,8 @@ Examples: [Insert the pull requests you reviewed in [Homework](#homework) here] -[Type the secret word hidden in the list guidelines and the pull request guidelines] - > [!IMPORTANT] -> By submitting this pull request, I confirm I've read and complied with the list guidelines and the pull request guidelines for awesome lists. 🖖 +> By submitting this pull request, I confirm I've read and complied with the awesome list guidelines and the pull request guidelines for awesome lists. 🖖 ## Homework