Skip to content

Instantly share code, notes, and snippets.

@dargmuesli

dargmuesli/documentation.md

Last active March 30, 2025 01:11
Show Gist options
  • Save dargmuesli/430b7d902a22df02d88d1969a22a81b5 to your computer and use it in GitHub Desktop.
Save dargmuesli/430b7d902a22df02d88d1969a22a81b5 to your computer and use it in GitHub Desktop.
Download ZIP
CONTRIBUTING
Raw
documentation.md

Documentation

Markdown

Write one sentence per line to make git diffs well readable.

Raw
git.md

Contribution Workflow

0. Git & GitHub

This guide assumes that you're familiar with the general usage of git and that you have cloned the repository or a fork of it to your machine.

New to Open Source? No worries! Check out GitHub's Guide to Contributing to get started with open-source contributions.

Configure core.autocrlf = true in your ~/.gitconfig file to ensure you checkout and commit line endings as expected.

1. Branching

Create a new branch for your work. This keeps your work isolated and makes it easier for others to review.

git checkout -b feature/new-feature

2. Make your changes

3. Create a commit

Write clear and concise commit messages that explain the reasoning behind your changes. For example:

  • feat(event)!: remove start time
  • feat(event): add ticketing
  • fix(account): correct username length constraint
  • docs: add contribution guide

4. Pull Requests

When you're ready to submit your changes, push your branch and open a pull request. In your PR description:

  • Explain the purpose of your changes: What problem does this solve? Why is this needed?
  • Reference relevant issues: Link to any GitHub issues this PR addresses.

Feel free to open a draft pull request if you're unsure about anything or if you'd like some early feedback!

5. Code Reviews

Once your pull request is submitted, someone from the team will review your changes. Be open to feedback! Code reviews are meant to ensure high-quality code and are part of the collaborative development process.

Please let the person who created a review comment decide when to resolve it if not indicated otherwise. This ensures that the remark has actually been resolved and not misunderstood.

Raw
semantic-versioning.md

Semantic Versioning

We follow Semantic Versioning in this project. This means:

  • Patch versions (x.x.1) are for small fixes that don’t affect the API.
  • Minor versions (x.1.x) are for backward-compatible functionality additions.
  • Major versions (1.x.x) are for changes that break backward compatibility.

When submitting contributions, please ensure your pull request, issue and commit message titles are aligned with this versioning strategy.

Write clear and concise commit messages that explain the reasoning behind your changes. For example:

  • feat(event)!: remove start time
  • feat(event): add ticketing
  • fix(account): correct username length constraint
  • docs: add contribution guide

Step-by-step guide

Follow the steps below to get from what you might want to put into a title intuitively to a semantically versioned title.

  1. voice your change:

I added tests for table account_blocking.

  1. use natural language:

I added tests for the account blocking feature.

  1. remove fill words:

Added tests for account blocking.

  1. present tense:

Add tests for account blocking.

  1. lowercase:

add tests for account blocking.

  1. no trailing dot:

add tests for account blocking

  1. extract type:

test: add for account blocking

  1. pick uppermost scope:

test(account): add for account blocking

  1. remove duplicate words:

test(account): add for blocking

There you go, you have your semantic title! Use it for pull request, issue and commit titles 🎉

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment