Workflow + Tips & Tricks

[verytactical]

General

• Each PR must have a "Closes #..." mention of the issue.
  • We should know what problem is being solved and why.
  • Prior to writing the code it should be known whether we even should do it, or that we should do it in this specific way.
• We're using issues for discussions of problems and their solutions
• We're only discussing exact code in PRs.
• Do not merge PRs without a formal approval from a reviewer.

Time

• Single issue should take no longer than half a day to finish (i.e. until it's merged).
• If the issue is longer than that, break it down into smaller issues.
• If breaking the issue into parts takes long time, create an issue for that with type Spike.

Issue types

• Plan: a group of sub-issues or sub-plans used to decompose a big task into a set of smaller ones; often times plans do not have an assignee because it's hard to pinpoint someone to them.
• Task: most common type of issues, means a small well-defined task (sometimes a task can be or even should be converted into a Plan and divided into sub-tasks).
• Spike: a small task to research and decompose a hard problem into several easy subproblems; since the expected outcome of a slike is a plan, spikes should be closed only after creating corresponding plans.
• Bug: for now, use it only if it blocks our public release.

CI issues

• If the spell-checker issues complaints for some new terms, add those to https://github.com/tact-lang/mintlify-ton-docs/blob/main/.vale/config/vocabularies/Custom/accept.txt in the same pull request
• If the formatter issues complaints, see the corresponding suggestions in the next step of the action workflow and as a separate comment on the same PR:
  

Mermaid diagrams

To display a Mermaid diagram, add a code block with the mermaid tag as such:

```mermaid
stateDiagram
  direction TB
  [*] --> Still
  Still --> [*]
  Moving --> Still
  Moving --> Crash
  Crash --> [*]
  Still --> s1
  Still --> Moving
```

It'll render into a similar diagram:

stateDiagram
  direction TB
  [*] --> Still
  Still --> [*]
  Moving --> Still
  Moving --> Crash
  Crash --> [*]
  Still --> s1
  Still --> Moving

Loading

Use https://mermaid.live and https://www.mermaidchart.com/play to interactively prototype your diagram. Once done, copy its textual representation and adjust a little to fit Mintlify.

One of the common issues is that many diagram names in Mintlify have to be suffixed with -beta, e.g., write not sankey but sankey-beta.