Once you've finished implementing and testing your changes, the final step is opening a Pull Request. A well written PR makes it easier for maintainers and reviewers to understand your work, provide feedback, and merge your changes quickly.

Remember that maintainers were not present while you developed your feature. Your PR should explain what you changed, why you changed it, and how someone else can verify that it works. Taking a few extra minutes to write a good PR description can speed up the review process.

Please do not use GitHub's web editor to make changes directly in the browser. Pull Requests created from GitHub web edits may be closed without review. Always clone the repository locally and submit changes from your fork.

Repository: https://github.com/project-wayfarer/wayfarer-14
Discord: https://discord.gg/QpVfma2eAp

Need help? Join the Discord server and ask questions in #mentorship-and-contributing. Everyone starts somewhere, and we're always happy to help new contributors.

Writing a Good Pull Request

Every Pull Request should answer four simple questions:

A reviewer should be able to understand your work without reading every changed file first.

Filling Out the PR Template

Wayfarer includes a Pull Request template to help provide all of the information reviewers need. Each section serves a specific purpose.

About the PR

Begin with a concise summary of what your Pull Request accomplishes. Focus on the end result rather than listing every file you edited.

Good examples include:

Adds a new mining scanner capable of detecting nearby ore veins.

Refactors shuttle docking logic to improve maintainability.

Fixes an issue where lockers could be opened while welded shut.

If your change is large, attempt to briefly explain how the new system works at a high level.

Why / Balance

Explain why the change was made. If the PR affects gameplay, discuss any balance reasons and discussions, issues, or design decisions.

Not every PR affects game balance. Documentation updates, bug fixes, and refactors may simply explain the problem they solve instead.

Technical Details

This section is intended for reviewers rather than players.

Summarize any implementation details that may not be obvious from the description alone. Mention significant code decisions, new systems, important refactors, or any areas where reviewers should pay particular attention.

Avoid repeating information already covered in the "About the PR" section.

How to Test

One of the most important sections of any Pull Request is the testing.

Reviewers should be able to follow your instructions and verify that the feature behaves correctly.

A good testing section might look something like:

1. Launch a local server.

2. Join as a Cargo Technician.

3. Purchase the new machine.

4. Verify it appears in the correct category.

5. Confirm all interactions function as expected.

If there are edge cases or known limitations, mention them here as well.

Media

If your Pull Request changes anything visible in-game like sprites, clothing, UI, maps, animations, or gameplay features; screenshots, GIFs, or short videos should be included demonstrating the changes.

Visual media allows reviewers to quickly understand the feature without having to build and run the game themselves.

Small code cleanups, documentation updates, or internal refactors usually do not require media.

Changelogs

Most gameplay changes should include a changelog entry so players know what has changed after the Pull Request is merged.

Wayfarer's changelog bot recognizes entries beginning with the :cl: marker.

For example:

:cl:
- add: Added a new experimental mining scanner.
- tweak: Adjusted shuttle purchase prices.
- fix: Fixed lockers ignoring welded doors.

Choose the changelog action that best matches your contribution:

Not every Pull Request requires a changelog. Internal refactors, documentation changes, or developer-only improvements generally do not.

Wayfarer-Specific Guidelines

In addition to the standard Pull Request process, Wayfarer has several project-specific conventions that contributors are expected to follow.

Keep new content inside _WF

Whenever possible, new Wayfarer-exclusive content should be placed inside the appropriate _WF directory rather than mixed into upstream files. This makes future upstream merges significantly easier and distinguishes custom Wayfarer content.

Comment changes to upstream files

If you need to modify an upstream C# or YAML file, clearly comment your changes so they can be identified during future upstream merges. For value changes, use the format:

# Wayfarer: OLD<NEW

For larger additions, surround the new code with Wayfarer and End Wayfarer comments where appropriate.

Cordinate map changes

If your Pull Request modifies an existing map or ship, communicate with the map's maintainer or original author before beginning work. Multiple contributors editing the same map simultaneously often results in merge conflicts that are difficult to resolve.

AI-Assisted Contributions

AI tools may be used to assist with development, but any generated code is your responsibility. Before submitting a Pull Request, please review, understand, and test any AI-assisted code.

AI-generated sprites, artwork, or other visual assets are not permitted in the repository. Submitting untested AI-generated code or AI-generated artwork may result in your Pull Request being rejected or being permanately banned from contributing.

Final Checklist

Before clicking Create Pull Request, ask yourself the following:

A clear, well-tested Pull Request is much more likely to receive a quick review and be merged fast. Taking the time to explain your work helps maintainers look at the quality of the implementation rather than trying to understand what changed.