docs: add port review template & revamp submission guidelines (#1937)

Co-authored-by: backwardspy <backwardspy@pigeon.life>
Co-authored-by: winston <hey@winston.sh>
main
Hamothy 2 years ago
parent b2393bb1f2
commit f09d28f98e

@ -0,0 +1,30 @@
title: "Name of the application/tool/website/etc"
body:
- type: markdown
attributes:
value: |
> **Note** <br>
> 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

@ -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!

@ -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!

@ -1,8 +0,0 @@
---
name: Org-Wide Issue
about: Report your issues with the Catppuccin Organisation here!
title: ''
labels: meta
assignees: ''
---

@ -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

@ -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

@ -3,94 +3,201 @@
</p>
<p align="center">
Guidelines for submitting and creating ports
Guidelines for submitting and creating ports
</p>
&nbsp;
### 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!
&nbsp;
### 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** <br>
> 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!
&nbsp;
### 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
```
&nbsp;
### 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.
&nbsp;
### 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 <name_of_your_port>
```
```
git clone https://github.com/catppuccin/template.git <name_of_your_port>
```
2. Navigate into the cloned repository
```
cd <name_of_your_port>
```
```
cd <name_of_your_port>
```
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!
&nbsp;
### 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!
&nbsp;
### 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 "`<emoji>` Soothing pastel theme for `<app name>`".
- Format the repo's description as "`<emoji>` Soothing pastel theme for
`<app name>`".
- `<emoji>` should be an emoji that you feel represents the app best.
- `<app name>` 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).
&nbsp;
### 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.
&nbsp;
### 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)).
&nbsp;
### 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.

Loading…
Cancel
Save