Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
437 lines (303 loc) · 13 KB

CONTRIBUTING.md

File metadata and controls

437 lines (303 loc) · 13 KB
title Contributing
tags
Guide
Internal
Developer

Contributing

This guide explains how to contribute to the TCAT Wiki.

Note that, while minor external contributions are welcome, this guide is primarily intended for use by TCAT/GS staff.

For a list of all guides on the TCAT Wiki, refer to the Guides List.

Version Control & Workflow

This project follows standardized version control conventions:

Semantic Versioning

The TCAT Wiki uses Semantic Versioning (MAJOR.MINOR.PATCH):

  • Major (X.0.0):
    • Core: New major features or upgrades
    • Docs: Changes to structure/navigation that break external links
  • Minor (0.X.0):
    • Core: Significant changes to core features
    • Docs: New documentation or major reworks
  • Patch (0.0.X):
    • Core: Minor fixes, fixing typos, completing chores
    • Docs: Small updates, fixing typos, adding images

Conventional Commits

Commits follow Conventional Commits with scoping:

  • feat(scope): description - Core features or Docs content
  • fix(scope): description - Core patches or Docs corrections

Examples:

feat(core-plugins): add abbreviations plugin
feat(docs-accessmap): add user manual page
fix(core-util): fix nav generator logic
fix(docs-walksheds): fix typo

Branch Naming

Follow GitHub flow with structured branch names:

Format: type/scope/<work-item-number>-short-description

Examples:

feat/core-plugins/1234-add-abbreviations-plugin
feat/docs-accessmap/1024-add-user-manual-page
fix/core-util/9876-fix-nav-generator-logic
fix/docs-walksheds/2048-fix-typo

Pull Request & Release Process

  1. Create a feature branch following the naming convention
  2. Make commits using conventional commit format
  3. Open a pull request to main and merge it

Changelog & Tagging a Release

Changelog entries and version tags are managed manually, not on every PR merge. Do this whenever a meaningful set of changes has landed on main:

  1. In VS Code Copilot Chat (agent mode), run:

    /changelog

    The prompt reads the commit history since the last tag, determines the correct Semantic Version bump, and prepends a new ### Features / ### Fixes entry to CHANGELOG.md.

  2. Review the generated entry — the prompt will flag any commits it omitted or that looked miscategorized.

  3. Commit the changelog update to main:

    chore: update changelog for vX.Y.Z

  4. On the GitHub website, go to Releases → Draft a new release.

    1. In Choose a tag, type the new version (e.g. v11.1.0) and select Create new tag on publish.
    2. Set the title to vX.Y.Z.
    3. Paste the release summary as the description.
    4. Click Publish release.

Getting Started (Windows 10/11)

This section of the guide explains how to set up a Windows environment for contributing to the TCAT Wiki for the first time.

Legend

  1. Keyboard shortcut to press | Action

    (Shift+C) | Copy

  2. Command to enter into terminal

    [someCommand --arguments \<path>]

Installation and Setup

  1. Install Visual Studio Code

    1. Install VS Code Extensions

      1. EditorConfig for VS Code

      2. Prettier

      3. Markdown All in One

      4. YAML

      5. Even Better TOML

  2. Clone the repository

    git clone https://github.com/TaskarCenterAtUW/tcat-wiki
cd tcat-wiki

  3. Install Python

  4. Set up Python virtual environment

    1. Create the virtual environment

      python3 -m venv .venv

    2. Activate the virtual environment

      .\.venv\Scripts\Activate.ps1

  5. Install requirements

    pip install -r requirements.txt

Editing Instructions

Refer to the documentation for Zensical.

Guide Files

By default, guides appear in both their parent page's guides section and in the main guides list. You can control this using frontmatter flags (YAML comments, invisible on the built page).

To exclude a guide from its parent's guides section:

---
title: Your Guide Title
tags:
    - Guide
# exclude-from-parent-guides-list
---

To exclude a guide from the main guides list:

---
title: Your Guide Title
tags:
    - Guide
# exclude-from-main-guides-list
---

Both flags can be used together to exclude a guide from all guides lists.

Content Style Guide

Use the golden samples in templates/content/README.md rather than live docs pages when checking content structure and formatting.

The full editor-facing guide lives in .github/instructions/content-style.instructions.md. Apply these conventions when writing or revising content in docs/:

  • Choose the closest golden sample before drafting or reviewing:
  • For multi-page tutorial indexes, combine the opening pattern from templates/content/tutorial.md with the table-of-contents pattern from templates/content/user-manual-index.md.
  • Open each guide with frontmatter, a ## page heading that matches the frontmatter title, a one-sentence opener, the standard Guides List reference, and a horizontal rule.
  • Use the required first sentence for the page type:
    • Tutorials and tutorial index pages begin with This tutorial...
    • User manual index pages begin with This user manual...
    • Tutorial and user manual subpages begin with This section...
  • Write for one clear user goal per page. Break procedures into ### sections and ordered lists, using either named steps or numbered subsections depending on the complexity of the workflow.
  • Use short, imperative steps. Bold exact UI labels and use code formatting for commands, filenames, IDs, placeholders, headers, and literal values.
  • When readers must substitute values, explain the placeholders once and provide a concrete example when it materially improves clarity.
  • Add screenshots only when they clarify a step or confirm a state. Place them directly after the relevant step and write alt text that identifies both the screen and the key focus area.
  • Use admonitions sparingly for cautions, waiting states, tips, and success confirmations.
  • Prefer plain language, active voice, and verified instructions over exhaustive explanation. Do not invent undocumented behavior or UI details.

Images

Where possible, follow these guidelines for images:

  1. Format: 24-bit .png

  2. Resizing: Scale images using { width="123" }:

    ![alt text](image.png){ width="300" }

Refer to Zensical: Images for more information.

Screenshots

For creating screenshots with a consistent style, Firefox DevTools is to be used.

  1. Open Firefox DevTools

    (F12)

  2. Open Responsive Design View

    (Ctrl+Shift+M)

  3. Add custom device profiles:

    1. Name: [Screenshot] Web - Portrait

      1. Size: 810x1440

      2. Device Pixel Ratio: 1

      3. User Agent String: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:140.0) Gecko/20100101 Firefox/140.0

    2. Name: [Screenshot] Web - Landscape

      1. Size: 1440x810

      2. Device Pixel Ratio: 1

      3. User Agent String: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:140.0) Gecko/20100101 Firefox/140.0

  4. It is recommended to remove all embedded metadata, such as with the use of ExifToolGUI.

  5. Process screenshots with the process-screenshot.py utility to generate themed light/dark variants with borders and drop shadows:

    # Ensure venv is activated first!
..\.venv\Scripts\Activate.ps1

# Process a single screenshot
python .\utilities\process-screenshot.py docs\resources\images\example\screenshot.png

# Process all images in a directory
python .\utilities\process-screenshot.py docs\resources\images\example\

# Process recursively with a custom profile
python .\utilities\process-screenshot.py docs\resources\images\ --recurse --profile uw-purple

# Regenerate existing output files
python .\utilities\process-screenshot.py screenshot.png --overwrite

    The script produces two variants per input image, saved as maximally-compressed lossless PNGs:

    • {name}-light.png — dark border + drop shadow for light theme pages
    • {name}-dark.png — light border + glow for dark theme pages

    Reference them in Markdown with Zensical's theme-switching fragments:

    ![Alt text](path/to/image-light.png#only-light)
![Alt text](path/to/image-dark.png#only-dark)

    Mode-tagged source files (e.g., image.light.png, image.dark.png) generate only the matching variant. Run with --help for all options including per-variant color/shadow overrides.

Image Annotations

For creating image annotations with a consistent style, follow these guidelines.

  1. Highlight box
    1. Use: Indicating an area of focus in an image.
    2. Style: Use the native keyboard navigation highlight
    3. Example: 
      ![Screenshot of TDEI Portal Dashboard page with the Copy API Key button highlighted.](docs/resources/images/workspaces/tutorial/workspace-export/dashboard-h-api-key-copy-light.png#only-light)
![Screenshot of TDEI Portal Dashboard page with the Copy API Key button highlighted.](docs/resources/images/workspaces/tutorial/workspace-export/dashboard-h-api-key-copy-dark.png#only-dark)
      Screenshot of TDEI Portal Dashboard page with the Copy API Key button highlighted. Screenshot of TDEI Portal Dashboard page with the Copy API Key button highlighted.
    4. Naming convention: For images with highlights, append -h-$highlightedFeature before the light/dark identifier.
      1. Example: dashboard-dark.png → dashboard-h-api-key-copy-dark.png
QR Codes
  1. Create QR codes using Project Nayuki's QR Code generator library.

Event Statistics

The event report system generates post-event summary reports.

# Ensure venv is activated first!
.\.venv\Scripts\Activate.ps1

# Generate a complete event report:
python .\utilities\generate-event-report.py --event olympia-connected

# Re-generate using cached stats:
python .\utilities\generate-event-report.py --event olympia-connected --skip-stats

# Run TM stats generator directly:
python .\utilities\event-reports\generate-tm-event-stats.py --event mny26

# Run ASR stats generator directly:
python .\utilities\event-reports\generate-asr-event-stats.py --event nda-vancouver

Run with --help for all available options.

Markdown Guide

Headers

# H1 Header
## H2 Header
### H3 Header
#### H4 Header
##### H5 Header
###### H6 Header

Text formatting

**bold text**
*italic text*
***bold and italic***
~~strikethrough~~
`inline code`

Links and images

[Link text](https://example.com)
[Link with title](https://example.com "Hover title")
![Alt text](image.jpg)
![Image with title](image.jpg "Image title")

Lists

Unordered:
- Item 1
- Item 2
  - Nested item

Ordered:
1. First item
2. Second item
3. Third item

Blockquotes

> This is a blockquote
> Multiple lines
>> Nested quote

Code blocks

```javascript
function hello() {
  console.log("Hello, world!");
}
```

Tables

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Row 1    | Data     | Data     |
| Row 2    | Data     | Data     |

Horizontal rule

---
or
***
or
___

Task lists

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Escaping characters

Use backslash to escape: \* \_ \# \`

Line breaks

End a line with two spaces
to create a line break.

Or use a blank line for a new paragraph.