Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
115 lines (85 loc) · 7 KB

CONTRIBUTING.md

File metadata and controls

115 lines (85 loc) · 7 KB

Contributing to Mainsail

If you are reading this document right now, you are probably considering contributing to Mainsail and making it better than it is today. Thank you for taking that initiative! Before submitting your contribution, please take a moment and make sure to read through our contribution guidelines:

Got a Question or Problem?

Please do not open issues for general support questions. We want to keep GitHub issues for bug reports and feature requests. Instead, please visit us on Discord to ask support-related questions.

Our Discord server is a much better place to ask general support questions. We take a right to close issues that are requests for generic support and redirect people to Discord.

Found a Bug?

If you find a bug in the source code or think that Mainsail is behaving odd in specific situations, you can help us fix that issue by submitting an issue. If you have already fixed that issue, you can submit a Pull Request with that fix.

Missing a Feature?

You can request a new feature by submitting a feature request. If you would like to implement a new feature, please consider the scope of the change. For changes requiring a lot of work, it's best to outline a proposal first so it can be discussed. This allows us to prevent wasted time and effort and discuss how to bring your proposed feature into the project.

Submission Guidelines

Submitting an Issue

Before you submit an issue, please search the issue tracker if your problem may already exist. If a ticket already covers your case, please refrain from opening a new ticket and instead contribute to the existing ticket. If you submit an issue, please provide the required information and reproduction steps. We need those to be able to try and reproduce the bug ourselves. Without proper instructions on how to reproduce the issue you are encountering, we might be unable to fix a possible bug.

Submitting a Pull Request (PR)

Before you work on a PR and submit it, please pay attention to the following guidelines:

  1. Search the pull requests for an open or closed PR related to your submission.

    • You don't want to duplicate existing efforts or work on something unlikely to be merged into the project.

  2. Do not submit PRs against the master branch. PRs need to be submitted against the develop branch.

  3. Follow our Code Standards

  4. If there is an issue describing the problem you're fixing or a discussion of a feature you are implementing, make sure to link it in the PRs body.

    • You can also add fix #<id> or fixes #<id> in the PR body where <id> is the issue id.
    • Example PR title, body and sign-off:
    fix: incorrect handling of click event

This PR will fix #123.
Fixes correct handling of click event when button [X] is clicked.

Signed-off-by: James Smith <james.smith@myvalidemail.com>

  5. If there is no issue describing the problem, create an issue first or provide a sufficient description of the bug/feature.

    • Screenshots of your changes are welcome if you worked on UI-related code.

  6. The title of the PR should follow the commit message convention.

    • If the PR consists of multiple commits, it's good practice to follow the convention, although that is not necessarily required.
    • Upon merging, we will squash all commits of the PR into a single commit for a clean history and release changelogs.

  7. Please sign off each commit and your PR. It must contain your real name and a current email address (see example in item 4).

    • The sign-off should follow this pattern: Signed-off-by: My Name <myemail@example.org>
    • The sign-off certifies that you agree with the developer certificate of origin.
    • If you provide a translation, a sign-off is not necessarily required.

  8. When opening a pull request, keep Allow edits and access to secrets by maintainers enabled.

Contributor Trust (Vouch System)

To protect the project from low-quality and automated spam contributions, Mainsail uses a vouch-based trust system for pull requests.

  • Pull requests may only be opened by vouched contributors. PRs from users who are not on the vouched list are automatically closed.
  • Maintainers and collaborators with write access, as well as bots (e.g. Dependabot), are always allowed and do not need to be vouched.

The list of vouched contributors is maintained in .github/VOUCHED.td.

How to Become a Trusted Contributor

If your PR was closed because you are not yet vouched, this is not a rejection of your work, and it is not permanent. The vouch system simply asks new contributors to build a little trust with the project first. Here is how you can get vouched:

  • Engage with the community. Open well-described issues, help others reproduce or diagnose bugs, and join the discussion on our Discord server. Issues are open to everyone and are a great first step.
  • Start small. Smaller, focused, and well-documented pull requests are easier to review and help maintainers get to know your work.
  • Be responsive. Reply to questions and review feedback on your issues and PRs.

Once a maintainer vouches for you, you become a trusted contributor. You can then reopen your closed PR or comment /recheck to have it re-evaluated, and your future pull requests will no longer be closed automatically. If you believe you should already be vouched, feel free to reach out to a maintainer on Discord.

Financial Contribution

As a community-driven project without primary corporate backing, we always welcome financial contributions. A list of options we offer to support us financially can be seen below.