catppuccin/docs/port-creation.md

<p align="center">
  <h2 align="center">🧱 Port Creation</h2>
</p>

<p align="center">
	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!

&nbsp;

### Submission

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

&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/servers/catppuccin-907385605422448742) and share it there too!

**Q. What types of ports won't be accepted?**

**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.

1. Clone template repository

   ```
   git clone https://github.com/catppuccin/template.git <name_of_your_port>
   ```

2. Navigate into the cloned repository

   ```
   cd <name_of_your_port>
   ```

3. Delete the `.git` folder at the root of the repository and run `git init`. This removes the template authors from appearing as contributors to your new port.

4. Set up the rest of your port, and push it to your user repository!

&nbsp;

### Styling

After creating the repo successfully, it's important to style it properly to
ensure consistency:

- 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>`".
  - `<emoji>` should be an emoji that you feel represents the app best.
  - `<app name>` is the name of the app, capitalized properly.
- 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).

&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
a layered screenshot of your port which combines all four flavors into one.