Skip to content

Contributing

Thanks for helping improve UOCompanion!
We use the standard fork → branch → pull request workflow.

0. Requirements

  • Git + GitHub account
  • Python 3.x (for local preview)
  • Optional: pipx or virtualenv

1. Fork and Clone

Fork the repository on GitHub (click Fork).
Clone your fork locally:

git clone https://github.com/YOURUSER/uocompanion.github.io.git
cd uocompanion.github.io
Add the original repository as an upstream remote:

git remote add upstream https://github.com/UOCompanion/uocompanion.github.io.git

git remote -v

2. Create a Feature Branch

Always branch from the latest main.

git fetch upstream
git checkout main
git merge --ff-only upstream/main  # or: git rebase upstream/main
git push origin main
git checkout -b docs/short-topic-name

3. Set Up and Preview Locally (MkDocs)

python -m venv .venv
. .venv/bin/activate   # Windows: .\.venv\Scripts\activate
pip install -r requirements.txt

# Live preview at http://127.0.0.1:8000
mkdocs serve

Make your edits under docs/, then verify that the site builds cleanly:

mkdocs build

4. Commit and Push

git add -A
git commit -m "docs: clarify X in Y page"
git push -u origin docs/short-topic-name

5. Open a Pull Request

  • Go to your fork on GitHub → Compare & pull request

  • Base repository: UOCompanion/uocompanion.github.io → base branch main

  • Head repository: YOURUSER/uocompanion.github.io → your feature branch

  • Fill out the PR template and submit for review

6. Keep Your PR Up to Date

If main changes while your PR is open:

git fetch upstream
git checkout docs/short-topic-name
git rebase upstream/main
# resolve conflicts if any, then:
git push --force-with-lease

Use --force-with-lease (not plain --force) for safety.

7. Review Cycle

  • Respond to reviewer comments with follow-up commits

  • Ensure mkdocs build succeeds (no warnings in strict mode)

  • Maintainers will squash-and-merge or rebase-merge after approval

Guidelines

Our site is built as a static documentation project, so clarity and simplicity matter most.
Use concise, well-structured Markdown. Images are welcome when they add value, but prefer words, tables, and data to communicate information whenever possible.