Workflow & Guidelines

To facilitate multiple people working on and reviewing docs simultaneously, following this workflow is required for all contributors.

If you are unfamiliar with Git, GitHub and/or VS Code, click the footnotes referenced on the steps for more detailed instructions.

Running the website locally

In order to see your changes live, start the website locally.

1. Open a Terminal in the project root directory and run:

   pnpm dev

2. Once the server starts, a URL will be provided in the console that you can click to open the local version of the website.
3. The local version should self-refresh as you make changes. If you don’t see a change, try refreshing the page in your browser.
4. When you’re done, click inside of the terminal and press Ctrl+C to stop the server.

Note

If you receive an error about a missing package when you try to start the server, run:

  pnpm i

Document Editing Workflow

1. In the project, open the issue in the “Ready” column and assign yourself to it (click “Assignees”. It’s in the “Metadata” section at the bottom of the sidebar view, or along the right in the full page issue view).

   Do not pick up any issues from the “Backlog” column.

2. Drag the issue into the “In Progress” column.

3. In VS Code, switch to the main branch¹ and pull².

4. Create a new branch³ (VS Code switches to the new branch automatically).

   Note

   Branch names should be ‘lowercase-with-hyphens’ (no spaces). If working on one doc, the branch name should be the doc name. Otherwise, try to come up with a meaningful but short name.

5. Make your changes/additions.

6. Stage⁴ and Commit⁵ your changes/additions.

   Note

   Commit messages should be written in the imperative, meaning they should make grammatical sense if appended after the phrase “if applied, this commit will…”. Example: “create the EuroScope doc”.

   Tip

   If you get an error while committing, click the “View Command Output” button. Look for ESLint errors and fix them before you commit again. If you see an error from Prettier saying you haven’t formatted a document, ensure you have set up the Prettier Extension properly to run on save.

7. Pull², then check the Graph view in the Source Control pane in VS Code for any new commits pushed to main that aren’t on your branch. If you see any, merge⁶ them into your branch.

8. Push⁷ the commits to GitHub on your branch.

9. Open a pull request⁸ (PR). Write the PR title in the imperative mood, similar to a commit message. In the description, ensure the phrase “Closes #n” is present on its own line at the bottom. Replace ‘n’ with the issue number⁹. This will auto-move your Issue to “Done” once your PR is merged and link it to your PR.

10. After creating your PR, assign yourself to the PR in the same way you did for the issue, then request a review¹⁰ from at least one contributor who was not involved with your work.

11. In the project, drag your issue into the “In Review” column.

12. After the contributor approves your review, request a review¹⁰ from the project lead and move your issue into the “KT Review” column.

13. Once your PR has been reviewed and merged, switch back to the main branch, pull and delete your branch¹¹.

General Guidelines

• Never commit or push directly on the main branch. Always use a separate branch and a pull request.
• Your work shouldn’t require modifying anything outside of the src/content/docs folder. If you feel outside changes are required, please speak to tech support first.
• Ensure you’re on the right branch before you commit.
• Pull and push regularly. At a minimum, pull before you start work on a given day and push once you’re done for the day if you’ve committed anything. If you are collaborating with someone else on the same branch, do this more often as you may need to resolve merge conflicts⁶ when you pull.
• Commit regularly; at least once when you finish writing a new file and for each major change. Think of committing like a slightly less frequent version of saving with a name for each ‘save’. You don’t only want to save once at the very end.
• Generally, if your commit message contains ‘and’, you may have too many changes lumped into one commit. VS Code allows you to selectively commit only certain sections of each file so you can break up the commits¹².
• Don’t reuse branches. Delete them after the relevant pull request has been merged.
• Take the time to review pull requests in detail to avoid having to go back and make more changes after the fact. GitHub has a great guide on how to review pull requests. Use the feature to comment on specific lines whenever you can to make responding to your review easier.

Footnotes

1. Switching between branches in VS Code ↩

2. Pulling in VS Code. If you’re collaborating with someone on the same branch and encounter a merge conflict while pulling, see the footnote about merge conflicts⁶. ↩ ↩²

3. Creating a Branch in VS Code ↩

4. Staging changes in VS Code ↩

5. Committing in VS Code ↩

6. Follow the instructions in Merging Branches in VS Code. Note however that unlike the example, the ‘target’ branch is your working branch, and you merge FROM main.

   You may encounter merge conflicts when merging or pulling. If that happens, see Resolve Merge Conflicts in VS Code. Always resolve merge conflicts using the 3-way merge editor. Do not attempt to resolve them inline. Always consider each conflict carefully to ensure you don’t overwrite someone else’s work. ↩ ↩² ↩³

7. Pushing Commits in VS Code ↩

8. Creating a PR on GitHub. The base branch should always be main, and the compare branch should be your branch. ↩

9. Linking pull requests to issues using keywords on GitHub ↩

10. Requesting reviews from collaborators on GitHub ↩ ↩²

11. Deleting branches in VS Code. You should delete the remote branch first (the one that’s been pushed to GitHub), followed by your local branch. Both can be done through VS Code. ↩

12. Stage specific lines for committing in VS Code ↩