Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
225 lines (149 loc) · 11.5 KB

CONTRIBUTING.md

File metadata and controls

225 lines (149 loc) · 11.5 KB

Contributing Guidelines

First off, thank you for considering contributing to this project.

Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open-source project. In return, they should reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests.

This is an open source project, and we love to receive contributions from our community — you! There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests, or writing code that can be incorporated into the SnapX itself.

Ground Rules

By contributing to this project, you agree to follow our Code of Conduct.
Please read this next section carefully and check if your contribution meets all requirements in this checklist.
This will save you and us a lot of time.

Issues: Feature Requests & Bug Reports

Please make sure you have checked all the following before submitting a new issue.

  • Before submitting a new issue, search the existing (including closed) issues for any duplicates.
  • If you found an existing issue, use the react feature to show you have the same problem or need the same feature. Don't post comments like +1.
  • Use the Bug & Feature Issue templates and provide all the required information.
  • Be as detailed as possible and include screenshots wherever possible. This will help reproduce your bug or understand your feature request.
  • Refer to our AI policy.
  • Do not bump SnapX's version in conventional pull requests. Only release branches like develop, alpha, and beta can do that.

Contributing Code

Pull requests are the best way to propose changes to the codebase (we use GitHub Flow). We actively welcome your pull requests:

Your First Contribution

Unsure where to begin contributing to this project? You can start by looking through these beginner and help-wanted issues: Good first issues - issues which should only require a few lines of code, and a test or two. Help wanted issues - issues which should be a bit more involved than beginner issues.

Remember, all the code and comments you write should be in American English.

Working on your first Pull Request? You can learn how from this article, How to Contribute to an Open Source Project on GitHub.

At this point, you're ready to make your changes! Feel free to ask for help; everyone is a beginner at first 😸

If a maintainer asks you to "rebase" your PR, they're saying that a lot of code has changed in the develop branch, and that you need to update your branch, so it's easier to merge.

Getting started

  1. Fork the repo and create your branch from develop. Name it accordingly using the Conventional Branch standard.
  2. If you've added code that should be tested, add tests.
  3. If you've changed APIs or added new features, update the documentation.
  4. Ensure the test suite passes.
  5. Test your changes.
  6. Commit & Push.
  7. Send the dang pull request to the develop branch.

Code review process

The core team will look at your change as soon as possible and review it. However, since this is a project that is done in free time, reviewing might sometimes take some time.

Code, commit message, and labeling conventions

We have very precise rules over how our Git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the commit history.

It is important to note that we use the Git commit messages to generate the CHANGELOG document. Improperly formatted commit messages may result in your change not appearing in the CHANGELOG of the next release.

Commit Message Format

Each commit message consists of a header, a body, and a footer. The header has a special format that includes a type, a scope and a subject:

<type
  >(<scope
    >):
    <subject>
      <BLANK LINE>
        <body>
          <BLANK LINE> <footer></footer></BLANK></body></BLANK></subject></scope
></type>

Any line of the commit message cannot be longer than 100 characters!
This allows the message to be easier to read on GitHub as well as in various Git tools.

Type

Must be one of the following:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semicolons, etc.)
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing tests
  • ci: Anything related to the CI/CD process, i.e., GitHub Actions
  • build: Anything related to the building process, including packaging such as RPM
  • chore: Everything else
Scope

The scope could be anything that helps to specify the scope (or feature) that is changing.
It is not required.

Examples

  • Avalonia
  • CLI
  • spec (snapx.spec)
  • PKGBUILD (PKGBUILD)
  • CommonUI
  • SharpCapture
  • NMH (NativeMessagingHost)
  • Core
Subject

The subject contains a succinct description of the change:

  • Use the imperative, present tense: "change"; not "changed" nor "changes"
  • Don't capitalize the first letter
  • No dot (.) at the end
Body

Just as in the subject, use the imperative, present tense: "change"; not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior.

Footer

The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit Closes, Fixes, or Relates to.

Breaking Changes are intended to be highlighted in the CHANGELOG as MAJOR. The major version is increased IF:

  • A release contains major UI/functionality updates (e.g., new interface design) that significantly change the user workflow.
  • Breaking changes to the CLI (e.g., removing/renaming flags, changing output formats) that require users to update their scripts.
Sample Commit messages
fix(ui): avoid loading tray icon when show is set to false

* for some reason, setting show: false in the window options makes it render

Fixes #11231

feat(settings): add new setting to enable dark mode

* new setting added to enable dark mode

Fixes #3857

refactor(Core): use asynchronous save instead of sync

Current development focus / where to contribute

The current focus is working on the SnapX.Avalonia UI. It's currently what's missing the most. The core code is going to be rewritten in the future, but contributions are welcome everywhere.

Releasing a new version of SnapX

One of the major benefits of this approach is that it will automatically release a new version on every successful push to either develop based on the commit messages. This ensures SnapX is released according to the semantic versioning guidelines. For this to work, you have to follow a few simple rules:

  • The master branch should always have working code that is tested. Use Pull Requests to work on bigger features or bug fixes and merge them when you are ready.
  • Every bugfix, feature, and change should have one commit associated with it. Do not mix multiple bugs, features, etc., into one huge commit message. Keep your commit size small and commit often.
  • Your commit messages must follow the conventional commit rules. Additionally, the Angular flavor is accepted as well.
  • While the version is v0.x.y, breaking changes will result in an increase of the Minor version. The Major version will remain 0 until the initial stable release (v1.0.0).

Versioning Rules

  • MAJOR version bumps are triggered by breaking changes, fundamental UX shifts, and massive internal rewrites.
  • MINOR version bumps are for backward-compatible feature additions.
  • PATCH version bumps are for bug fixes and small changes.

For example:

  • 1.2.3 → 2.0.0 if there's a breaking config change or a removed feature.
  • 1.2.3 → 1.3.0 if a new tool is added to the UI.
  • 1.2.3 → 1.2.4 if a bug fix is made.

When does a version bump happen?

The version bump is automatically determined based on your commit messages. Here’s how it works:

Commit Type Results In Example Commit Message Example
BREAKING CHANGE: or ! after type MAJOR bump feat!: drop support for legacy config format Breaking changes to CLI or saved config
feat: MINOR bump feat: add new image export option New image export format, new setting, new shortcut
fix:, perf: PATCH bump fix: resolve crash on launch Fix crash on launch, UI glitch, memory leak fix
chore:, docs:, refactor:, etc. No bump chore: update build script Chore, doc update, refactoring, test-only changes

💡 Conventional Commits aren’t about rules — they’re about making history readable.

Contribution Guidelines

  • The master branch should always contain stable and tested code.
    Use Pull Requests for all features or bug fixes. Merge them only when ready.

  • Each bug fix, feature, or change should have one commit associated with it.
    Avoid mixing multiple changes into a single commit.

  • All commits must follow Conventional Commit format.
    We accept the Angular flavor (e.g., feat:, fix:) and support semantic bump hints.

AI policy

Okay, so here's the thing:

  • No GitHub issues generated by AI.
    It won't be reviewed if it was written by a chatbot. Only open issues if you truly comprehend the feature or bug you're describing.

  • No "vibe coding".
    Just because "it works on your machine" doesn't mean you should submit the code. It doesn't belong here if you can't explain what it does or why.

AI-assisted coding is acceptable. Copilots, linters, refactors, and other tools that speed up your work are all great as long as you understand what's happening behind the scenes.

Note: SnapXL doesn’t use AI in its own development.

One More Thing

All commits from humans, i.e., (NOT GitHub Actions), should be signed. Please take some time to learn how to sign your commits if you haven't already.