From f09d28f98ed786107ffbdd016dc103e707a42042 Mon Sep 17 00:00:00 2001 From: Hamothy <58985301+sgoudham@users.noreply.github.com> Date: Mon, 27 Feb 2023 22:56:50 +0000 Subject: [PATCH] docs: add port review template & revamp submission guidelines (#1937) Co-authored-by: backwardspy Co-authored-by: winston --- .github/DISCUSSION_TEMPLATE/port-request.yml | 30 +++ .github/DISCUSSION_TEMPLATE/port-requests.yml | 24 --- .github/ISSUE_TEMPLATE/config.yml | 2 +- .github/ISSUE_TEMPLATE/org-wide-issue.md | 8 - .github/ISSUE_TEMPLATE/org-wide-issue.yml | 17 ++ .github/ISSUE_TEMPLATE/port-review.yml | 26 +++ docs/port-creation.md | 197 ++++++++++++++---- 7 files changed, 226 insertions(+), 78 deletions(-) create mode 100644 .github/DISCUSSION_TEMPLATE/port-request.yml delete mode 100644 .github/DISCUSSION_TEMPLATE/port-requests.yml delete mode 100644 .github/ISSUE_TEMPLATE/org-wide-issue.md create mode 100644 .github/ISSUE_TEMPLATE/org-wide-issue.yml create mode 100644 .github/ISSUE_TEMPLATE/port-review.yml diff --git a/.github/DISCUSSION_TEMPLATE/port-request.yml b/.github/DISCUSSION_TEMPLATE/port-request.yml new file mode 100644 index 0000000..1167f0c --- /dev/null +++ b/.github/DISCUSSION_TEMPLATE/port-request.yml @@ -0,0 +1,30 @@ +title: "Name of the application/tool/website/etc" +body: + - type: markdown + attributes: + value: | + > **Note**
+ > If you have already themed your port and are looking to get it reviewed, please raise a [port review](https://github.com/catppuccin/catppuccin/issues/new?assignees=&template=port+review.yml&title=Name+of+the+application%2Ftool%2Fwebsite%2Fetc.) issue instead! + - type: checkboxes + attributes: + label: Will you make the port? + description: The port has a much higher chance of completion if you are willing + to get involved! + options: + - label: Yes, I'm willing to make the port + - type: textarea + attributes: + label: How can the suggested port be themed? + description: Please link to relevant documentation or other examples of themes + being applied to the suggested port. + - type: textarea + attributes: + label: Any additional comments? + description: Add any information that hasn't been covered in the previous sections! + - type: checkboxes + attributes: + label: Submission Guidelines + description: By suggesting this port, you have followed our [submission guidelines](https://github.com/catppuccin/catppuccin/blob/main/docs/port-creation.md#submission) + options: + - label: I have read and followed Catppuccin's submission guidelines. + required: true diff --git a/.github/DISCUSSION_TEMPLATE/port-requests.yml b/.github/DISCUSSION_TEMPLATE/port-requests.yml deleted file mode 100644 index 74d3404..0000000 --- a/.github/DISCUSSION_TEMPLATE/port-requests.yml +++ /dev/null @@ -1,24 +0,0 @@ -title: "Name of the application/tool/website/etc" -body: - - type: markdown - attributes: - value: | - Before you submit your port request, **please read our [submission guidelines](https://github.com/catppuccin/catppuccin/blob/main/docs/port-creation.md#submission)!** - - type: checkboxes - attributes: - label: Will you make the port? - description: The port has a much higher chance of completion if you are willing to get involved! - options: - - label: Yes, I'm willing to make the port - - type: textarea - attributes: - label: How can the requested port be themed? - description: Please link to relevant documentation or other examples of themes being applied to the requested port. - - type: textarea - attributes: - label: Has the requested port been themed already? - description: Please link the repository of the codebase or any screenshots of the requested port. - - type: textarea - attributes: - label: Any additional comments? - description: Add any information that hasn't been covered in the previous sections! diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 293b8e8..6820244 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -2,7 +2,7 @@ blank_issues_enabled: false contact_links: - name: Port Request url: https://github.com/catppuccin/catppuccin/discussions/new?category=port-requests - about: Make your port requests via GitHub discussions! + about: Have an idea for a port or currently theming one? Raise a discussion here! - name: Community Discord url: https://discord.com/invite/r6Mdz5dpFc about: Ask questions and chat to other community members! diff --git a/.github/ISSUE_TEMPLATE/org-wide-issue.md b/.github/ISSUE_TEMPLATE/org-wide-issue.md deleted file mode 100644 index 2975e5f..0000000 --- a/.github/ISSUE_TEMPLATE/org-wide-issue.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -name: Org-Wide Issue -about: Report your issues with the Catppuccin Organisation here! -title: '' -labels: meta -assignees: '' - ---- diff --git a/.github/ISSUE_TEMPLATE/org-wide-issue.yml b/.github/ISSUE_TEMPLATE/org-wide-issue.yml new file mode 100644 index 0000000..482a9ac --- /dev/null +++ b/.github/ISSUE_TEMPLATE/org-wide-issue.yml @@ -0,0 +1,17 @@ +name: Org-Wide Issue +description: Report your issues with the Catppuccin Organisation here! +labels: [meta] +body: + - type: checkboxes + attributes: + label: Is there an existing issue for this? + description: Please search to see if an issue already exists for your concerns. + options: + - label: I have searched the existing issues. + required: true + - type: textarea + attributes: + label: What is your concern? + description: Raise your concern regarding the Catppuccin organisation. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/port-review.yml b/.github/ISSUE_TEMPLATE/port-review.yml new file mode 100644 index 0000000..72cb564 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/port-review.yml @@ -0,0 +1,26 @@ +name: Port Review +description: Have a port already themed? Submit it for review here! +title: "Name of the application/tool/website/etc." +body: + - type: input + attributes: + label: Link to repository + description: Please link the repository of the port. + placeholder: https://github.com/user/example.git + validations: + required: true + - type: textarea + attributes: + label: Screenshots + description: Show off some screenshots of the completed port! + - type: textarea + attributes: + label: Any additional comments? + description: Add any information that hasn't been covered in the previous sections! + - type: checkboxes + attributes: + label: Submission Guidelines + description: By submitting this port for review, you have followed our [submission guidelines](https://github.com/catppuccin/catppuccin/blob/main/docs/port-creation.md#submission) + options: + - label: I have read and followed Catppuccin's submission guidelines. + required: true diff --git a/docs/port-creation.md b/docs/port-creation.md index 1c81345..6b68d18 100644 --- a/docs/port-creation.md +++ b/docs/port-creation.md @@ -3,94 +3,201 @@

- Guidelines for submitting and creating ports + Guidelines for submitting and creating ports

  ### What's a port? -A port is an adaptation of Catppuccin's palette for an app to use. Think of it as a colorscheme for a program -that styles every UI component it consists of! +A port is an adaptation of Catppuccin's palette for an app to use. Think of it +as a colorscheme for a program that styles every UI component it consists of!   ### Submission -Raise a discussion under main -repository [here!](https://github.com/catppuccin/catppuccin/discussions/new?category=port-requests) The title should be -the **simplest** name of the application/tool/website/etc that you are wanting ported over. +> **Note**
+> All ports should conform to our +> [CODE OF CONDUCT](https://github.com/catppuccin/.github/blob/main/CODE_OF_CONDUCT.md) +> and we, the staff team, reserve the right to choose what ports will be +> included under the organization. + +Read through the following headings to ensure that you're adhering to our +submission guidelines! + +- [Workflow](#workflow) - View the ideal Catppuccin port workflow from start to + finish! +- [FAQ](#faq) - Unsure where to start? You can find the answers to your + questions here! +- [Creation](#creation) - Start creating your ports with our template + repository! +- [Styling](#styling) - Already started work on your port? Make sure you're + following our style guidelines! +- [Licensing](#licensing) - Important information about the licensing of ports + underneath the organization! +- [Maintenance](#maintenance) - Details on the maintenance of ports after they + have been transferred into the organization! -If you have already created a repository containing the work, make sure to include it within the description for others -to see! Feel free to join our [Discord](https://discord.com/invite/r6Mdz5dpFc) and share it there too! +  + +### Workflow + +```mermaid +stateDiagram-v2 + idea: You have an idea for a port + idea --> choice + + choice: Have you already completed a draft? + choice --> draft_complete: Yes + choice --> request: No + + request: Open a Port Request discussion + request --> request_picked_up + + request_picked_up: You or somebody else works on a draft + request_picked_up --> request_complete + + request_complete: The draft is completed to your liking + request_complete --> draft_complete + + draft_complete: Create a Port Review issue + draft_complete --> review + + review: Review period + review --> port_adoption + + note right of review + Community feedback + end note + + port_adoption: Port adoption +``` + +  + +### FAQ + +**Q. I have a port that is already themed and ready for review!** + +**A.** Port reviews can be raised as an issue +[here](https://github.com/catppuccin/catppuccin/issues/new?assignees=&template=port+review.yml&title=Name+of+the+application%2Ftool%2Fwebsite%2Fetc.) +since the port is already themed and ready to be reviewed by our +[staff team](https://github.com/orgs/catppuccin/teams/staff/members)! + +**Q. I have a request for a port to be included and/or I've started working on +it!** + +**A.** Raise a discussion under main repository +[here](https://github.com/catppuccin/catppuccin/discussions/new?category=port-requests)! +The discussion will be transferred to an issue by the +[staff team](https://github.com/orgs/catppuccin/teams/staff/members) once we +have deemed the port ready to be reviewed! Feel free to join our +[Discord](https://discord.com/invite/r6Mdz5dpFc) and share it there too! -The discussion will be transferred to an issue by -the [staff team](https://github.com/orgs/catppuccin/teams/staff/members) once we have deemed the port ready to be -reviewed and merged! +**Q. What types of ports won't be accepted?** -All ports should conform to our [CODE OF CONDUCT](https://github.com/catppuccin/.github/blob/main/CODE_OF_CONDUCT.md) -and we, the staff team, reserve the right to choose what ports will be included under the organisation. As a -community-driven project, we want to keep a neutral environment for all users. Therefore, **we do not accept -contributions that have a religious or political context.** However, we have no issue with our palette being used in +**A.** As a community-driven project, we want to keep a neutral environment for +all users. Therefore, **we do not accept contributions that have a religious or +political context.** However, we have no issue with our palette being used in these contexts.   ### Creation -You can create ports using [this](https://github.com/catppuccin/template) public template as a blueprint. +You can create ports using [this](https://github.com/catppuccin/template) public +template as a blueprint. 1. Clone template repository - ``` - git clone https://github.com/catppuccin/template.git - ``` + ``` + git clone https://github.com/catppuccin/template.git + ``` 2. Navigate into the cloned repository - ``` - cd - ``` + ``` + cd + ``` 3. Delete the existing remote - ``` - git remote remove origin - ``` + ``` + git remote remove origin + ``` 4. Set up the rest of your port, and push it to your user repository!   -### Licensing - -Any contribution will be published under the same licensing terms as the project itself. However, there -are [exceptions to this rule](https://github.com/search?q=org%3Acatppuccin+-license%3Amit). Please get in touch with us -if that is the case with your work! - -  +### Styling -### Styling! +After creating the repo successfully, it's important to style it properly to +ensure consistency: -After creating the repo successfully, it's important to style it properly to ensure consistency: - -- The name of the repo must be the simplest version of the app's name (e.g. `nvim` instead of `NeoVim`). You may use - hyphens if needed (e.g. `windows-files`). +- The name of the repo must be the app's name in `lower-kebab-case` (e.g. + `unreal-engine` instead of `Unreal Engine`). - Put the images under `assets/`. -- Format the repo's description as "`` Soothing pastel theme for ``". +- Format the repo's description as "`` Soothing pastel theme for + ``". - `` should be an emoji that you feel represents the app best. - `` is the name of the app, capitalized properly. -- Add `catppuccin`, and `theme` to the topics. +- Add `catppuccin`, `theme`, and the name of the application (e.g. + `unreal-engine`) to the topics. +- Ensure that you have generated the repository following the + [creation](#creation) steps. +- Ensure that the port README.md is styled appropriately following the steps + below: + - Where possible, try to use + [relative links](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#relative-links) + for linking assets. + - Update [shields.io](https://shields.io/) badges to point towards your + repository link instead of the template repository. + - The main preview image should be an image generated by + [catwalk](https://github.com/catppuccin/toolbox#catwalk). (e.g. + [vscode](https://github.com/catppuccin/vscode#catppuccin-for-vscode) and + [discord](https://github.com/catppuccin/discord#catppuccin-for-discord)) + - Add yourself to the **Thanks to** section \<3 - Ensure uppercase meta files (e.g. `README.md`) -- Don't add health files (e.g. `CODE_OF_CONDUCT.md`, `SUPPORT.md`), those are organization-wide files - stored [here](https://github.com/catppuccin/.github). +- Don't add health files (e.g. `CODE_OF_CONDUCT.md`, `SUPPORT.md`), those are + organization-wide files stored [here](https://github.com/catppuccin/.github). + +  + +### Maintenance + +The staff team wants to let you know that we understand submitting a port may +feel overwhelming. But don't worry, **we don't expect you to keep maintaining +your port after it's been transferred to us**. We would love for you to continue +helping out, but we understand if that's not possible. + +When you submit your port to be transferred, think of it as offering it up for +co-maintenance. This means you'll work with the staff team to maintain the port +together! Our main focus will be to maintain consistent quality and +accessibility standards across all ports. We'll also provide feedback on ways to +improve your port and help fix any technical issues. + +  + +### Licensing + +Any contribution will be published under the same licensing terms (MIT) as the +project itself. However, there are +[exceptions to this rule](https://github.com/search?q=org%3Acatppuccin+-license%3Amit). +Please get in touch with us, if the application you're theming has licensing +restrictions, or your work is a derivative of a stricter license (e.g. +[cursors](https://github.com/catppuccin/cursors#info)).   ### Tools -Since Catppuccin is available in 4 flavors it's understandable that it may be difficult to make 4 versions of a -port. So to help with that, we have built a bunch of tools to make life easier when creating Catppuccin ports. You'll -find them all (with instructions) under our [catppuccin/toolbox](https://github.com/catppuccin/toolbox) repo. -An essential tool for creating ports is [catwalk](https://github.com/catppuccin/toolbox#catwalk), this is used to create +Since Catppuccin is available in 4 flavors it's understandable that it may be +difficult to make 4 versions of a port. So to help with that, we have built a +bunch of tools to make life easier when creating Catppuccin ports. You'll find +them all (with instructions) under our +[catppuccin/toolbox](https://github.com/catppuccin/toolbox) repo. An essential +tool for creating ports is +[catwalk](https://github.com/catppuccin/toolbox#catwalk), this is used to create a layered screenshot of your port which combines all four flavors into one.