docs: add port review template & revamp submission guidelines

[sgoudham]

Motivation

As we recently switched over to GitHub discussions for our port requests, we have noticed a slight inefficiency in the new process. Ports are sometimes fully themed and ready to review before a discussion has been created. This is, of course, completely okay but results in a wasted step of creating the discussion and transferring it to an issue instantly.

Proposal

Create two types of port requests...

1. Port Requests (GitHub Discussions)
   • This is the same process we currently have for discussions. However, this will now be restricted to only WIP ports and suggestions/ideas for ports to be included within Catppuccin.
2. Port Reviews (GitHub Issues)
   • New issue template on the repository itself, ports that are already themed and ready for review should be raised here instead of the GitHub discussion.

We hope that this isn't too confusing for our existing maintainers and new maintainers to come.

P.S Sorry for the reformatting changes 😅

TODO List before/during merging

• Figure out the URL for port-review to reference within port-suggestion.md and port-creation.md
• Rename port-requests to port-suggestions in GitHub discussions
• Decide on a workflow visualization diagram to include in port-creation.md

[ghostx31]

Great PR Hammy! The document changes look good.

As for the URL for port-review, we can probably take some idea from catppuccin/cli which opens the issue template with the URL: https://github.com/catppuccin/cli/issues/new?assignees=&labels=bug&template=bug_report.md&title=.

[nekowinston]

Looks good, some quick thoughts since we're reworking this again.

Edit: didn't mean to mark this as ready, just a GitHub mobile moment.

[sgoudham]

Changing this back to draft because I want to add more stuff aside from PR comments

[backwardspy]

@catppuccin/staff we have put together a couple of options for visualising the port creation workflow here and here. these are of course rough drafts at this stage.

interested in your thoughts on how useful this will be, and whether another tool might be better (excalidraw et al.) we started with mermaid for ease of maintenance, however this does place restrictions on styling & layout.

[sgoudham]

Tidied up the docs as per PR comments, curious about what people think of the new port-creation.md

Tried to get everything underneath the #Submission heading and link off to it. Worth mentioning that the visualisation diagram is still a WIP!

[alythical]

I found the diagram by @nekowinston to be the easiest to follow because in the other two it didn't seem as clear where the workflow starts for people who already have completed themes that are ready for review.

[ghostx31]

@backwardspy I found winston's diagram easier to follow. Maybe we might add it to port-creation.md?
Also, about port-creation.md:

• catppuccin/docs/port-creation.md

  Line 160 in 98e67a4

  - Add `catppuccin`, and `theme` to the topics.

  
  We should also ask to add the app's name to the topics.

[nullishamy]

It would be nice if staff-transferred discussions and 'port reviews' were standardised to be the same / similar. Would further reduce friction and confusion for people reading the issues.

Other than that, LGTM, good work!

[sgoudham]

Really great point you've raised there @nullishamy

In the short term, I think there'll be a burden on staff to ensure that transferred issues are reformatted into the port-review template. In the longer term, I'd love the existence of a GitHub bot to automate the manual processes... one day :P

[sgoudham]

Just one thing that I noticed in your port workflow diagram, I was under the following impression

1. Port Requests (GitHub Discussions)
   • This is the same process we currently have for discussions. However, this will now be restricted to only WIP ports and suggestions/ideas for ports to be included within Catppuccin.
2. Port Reviews (GitHub Issues)
   • New issue template on the repository itself, ports that are already themed and ready for review should be raised here instead of the GitHub discussion.

The diagram seems to suggest that for port requests, we actually don't want WIP ports at all? Is that correct? @nekowinston

[backwardspy]

The diagram seems to suggest that for port requests, we actually don't want WIP ports at all? Is that correct? @nekowinston

this is tricky. there are really three cases, while the graph currently only shows two.

1. you want a port, and you don't want to make it.
2. you want a port, and you want to make it
3. you've already made a port

1 and 3 send you down the right process, but 2 implies you should wait until you've made the port. i think we definitely want to encourage the creation of a discussion in either case. perhaps the question "are you willing to make it" should instead be "have you made it already"?

[nekowinston]

The diagram seems to suggest that for port requests, we actually don't want WIP ports at all? Is that correct? @nekowinston

Ah no, sorry, that's not what I meant. I made the stateDiagram as a draft to show off the graph layout, so consider it a draft and not a finished graphic.

this is tricky. there are really three cases, while the graph currently only shows two.

stateDiagram-v2
  choice: Are you willing to make the port?
  choice --> author: Yes
  author: Work on a draft for a port
  author --> feedback_needed
  feedback_needed: Do you want feedback while porting?
  feedback_needed --> author_done : No
  feedback_needed --> request: Yes
  author_done: Once a port is finished, create an issue, requesting review from @staff
  choice --> request: No
  request: Open a Port Request discussion
  request --> author_done

Do we want something like this then?
Who do we want to create the issues from a discussion? Staff or the authors?

Here's how I understand what we're trying to achieve with rewording this, using @backwardspy's list:

1. you want a port, and you don't want to make it.
2. you want a port, and you want to make it
3. you've already made a port

1. Raise a discussion, for people to pick up
2. Raise a discussion to talk about the details of making it easy to maintain, etc.
3. Fast-tracking current org members so that they only have to create an issue

What we could also add (we're assuming that we're starting out at a port idea):

• Pointing people who want to work on something, but don't have an idea, to the discussions for inspiration

[backwardspy]

it seems to me that by changing the question at the start, we can keep the flow simple while covering (i think!) all cases:

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

thoughts?

[nekowinston]

Yeah I think that would cover everything. Way easier to read than more branches in the graph.

[sgoudham]

Before I merge this in, are you folks happy if I transfer the existing draft-available issues into discussions?

@nekowinston @backwardspy @ghostx31 @taka0o

[ghostx31]

Sure, it's a yes from me.

[nekowinston]

Yeah, but you can skip #152, I'm planning to make a repo for it this week, I already have it locally.

[sgoudham]

Drafts moved over, merging now. Thanks, everyone for the comments and feedback throughout this! ❤️