Contributing

How to contribute code, documentation, or bug reports to Provenance

Provenance is an open-source project and welcomes contributions from the community. Here's how you can help:

Ways to Contribute

Contribution	Where	Skill Level
Report bugs	GitHub Issues	Any
Improve documentation	Wiki repo	Any
Submit code fixes	Main repo (fork & PR)	Developer
Add features	Main repo (fork & PR)	Developer
Test beta builds	TestFlight or build from source	Intermediate
Share controller skins	DeltaStyles or Discord	Designer

---

Code Contributions (Fork & PR Workflow)

Provenance uses a fork-and-pull-request workflow — you work on your own fork and submit PRs back to the main repo. This means you don't need write access to contribute.

1. Create a Fork

1. Go to the Provenance GitHub page and click Fork

2. Clone your fork locally:

# Clone your fork (with submodules)
git clone --recurse-submodules -j4 [email protected]:YOUR-USERNAME/Provenance.git ProvFork
cd ProvFork

1. Add the upstream remote so you can pull future updates:

# Add the original repo as "upstream"
git remote add upstream [email protected]:Provenance-Emu/Provenance.git

# Verify remotes
git remote -v

2. Create a Feature Branch

Always work on a dedicated branch — never commit directly to develop:

git checkout -b feature/your-feature-name

3. Keep Your Fork Up to Date

Before starting work (and periodically while working), sync with upstream:

# Fetch latest from upstream
git fetch upstream

# Update your local develop branch
git checkout develop
git pull upstream develop
git push origin develop

# Rebase your feature branch on the latest develop
git checkout feature/your-feature-name
git merge upstream/develop

You can also use the Fetch upstream button on your fork's GitHub page.

4. Submit a Pull Request

PRs should contain all changes squashed into a single commit to keep the git history clean:

# Make sure you're on your feature branch
git checkout feature/your-feature-name

# Squash all commits into one
git reset --soft develop
git add -A
git commit -m "Add your feature description here"

# Push (force push needed since history was rewritten)
git push --force origin feature/your-feature-name

Then open a Pull Request on GitHub from your branch to Provenance-Emu/Provenance:develop.

---

Wiki / Documentation Contributions

The wiki lives in a separate repo. It's all Markdown files rendered by GitBook.

Quick fixes: Edit directly on GitHub (click the pencil icon on any file) and submit a PR.

Larger changes: Fork the wiki repo, make edits locally, and submit a PR to master.

Style notes:

• Use relative links between pages (e.g., [FAQ](../faqs.md))

• Preserve existing YAML frontmatter

• Update SUMMARY.md if adding or renaming pages

---

Reporting Bugs

Good bug reports help us fix issues faster:

1. Search first — Check existing issues to avoid duplicates

2. Use the latest version — Update from the App Store or build from the latest source

3. Include details:

   • Device model and OS version

   • Provenance version (Settings → About)

   • Steps to reproduce the issue

   • What you expected vs what happened

   • Screenshots or screen recordings if applicable

4. One bug per issue — Don't bundle multiple problems together

Before reporting: Make sure you installed from an official source. We cannot support 3rd-party builds or signing services.

---

Community

• Discord — Chat, help, and discussion

• GitHub Discussions — Feature requests and Q&A

• Twitter/X — Updates and announcements

Every contribution matters — whether it's a one-line typo fix, a detailed bug report, or a major feature. Thank you for helping make Provenance better!