Contributing to the project

A guide to contributing to the development of VasakOS. This applies to in-house or community work within the same environment.

Contribution process#

Fork and clone#

1
2
3
4
5
6
7
8
9
# On GitHub, fork the repository
# https://github.com/Vasak-OS/vasak-desktop

# Clone your fork
git clone https://github.com/YOUR_USER/vasak-desktop.git
cd vasak-desktop

# Add the original repository as a remote
git remote add upstream https://github.com/Vasak-OS/vasak-desktop.git

Create a branch#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# Update main from upstream
git fetch upstream
git checkout main
git merge upstream/main

# Create a branch for your feature
git checkout -b feature/short-description

# Or for a bugfix
git checkout -b bugfix/short-description

# Or for docs
git checkout -b docs/short-description

Naming convention:

feature/feature-name - New functionality
bugfix/bug-name - Bug fix
refactor/refactor-name - Refactoring
docs/doc-name - Documentation
chore/chore-name - Tasks with no functional code

Make your changes#

Make the changes in the project however you see fit for what you are trying to solve. Remember that you can use several commits if it helps you organise things, but avoid going overboard or having commits that make no sense on their own. Gather everything you think matters for the PR and for the documentation.

Checklist:

The code follows the guidelines
Tests pass
No linting errors
Documentation updated
Well-described commits

Commits#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# See the changes
git status

# Stage the changes
git add .

# Commit with a descriptive message
git commit -m "feat(audio): add volume normalization

Implement automatic volume normalization to provide
consistent output levels across different devices.

Closes #1234"

Message format (Conventional Commits):

1
2
3
4
5
type(scope): subject

body

footer

Types: feat, fix, docs, style, refactor, perf, test, chore

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
feat(audio): add volume normalization

Implement automatic volume normalization to provide
consistent output levels across different devices.
This prevents audio clipping and improves user
experience when switching between devices.

- Added VolumeNormalizer struct
- Integrated with audio pipeline
- Added unit tests

Closes #1234
Fixes #5678

Push and pull request#

1
2
3
4
5
6
# Push your branch
git push origin feature/short-description

# On GitHub, create a Pull Request
# Against: Vasak-OS/vasak-desktop main
# From: YOUR_USER/vasak-desktop feature/short-description

PR template (pre-filled):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
## Description
A brief description of what this PR does.

## Type of change
- [ ] New functionality
- [ ] Bug fix
- [ ] Change that breaks compatibility
- [ ] Documentation

## Changes
- Change 1
- Change 2
- Change 3

## Testing
- [ ] Tested on X11
- [ ] Tested on Wayland
- [ ] Unit tests pass
- [ ] Integration tests pass

## Checklist
- [ ] My code follows the guidelines
- [ ] I have self-reviewed
- [ ] I have commented complex code
- [ ] I have updated the documentation
- [ ] I have added tests
- [ ] The tests pass locally

## Benchmark (if applicable)

Review and feedback#

Maintainers will review your PR
Answer the comments
Make changes if needed
Request re-review once you have made changes

1
2
3
4
5
6
7
8
# After making changes
git add .
git commit -m "Address review feedback

- Changed X to Y
- Added comment for Z"

git push origin feature/short-description

Merge#

Once approved:

Maintainers will merge your PR
Your branch can be deleted

1
2
3
4
# Clean up locally
git checkout main
git branch -d feature/short-description
git pull upstream main

Types of contribution#

New features#

Steps:

Discuss it in an issue first
Follow the established architecture
Add tests
Document the change
Update the CHANGELOG

Bug fixes#

Steps:

Open an issue describing the bug
Create a branch from the issue
Reproduce the bug with a test
Fix the bug
The test should pass
Document the fix

Documentation#

Files:

docs/user/* - For end users | repo
docs/devs/* - For developers | repo
README.md - For the repository
Code comments - Inside the code

Performance improvements#

Requirements:

Measure first (with a profiler)
Implement the improvement
Measure afterwards (compare)
Add a benchmark if it is critical
Document the change

Tests#

Types:

Unit tests - Individual functions
Integration tests - Integrated components
E2E tests - The complete user flow

Location:

src-tauri/tests/ - Rust tests
src/tests/ - Vue tests

Bug reports#

See How to report bugs

Requires:

A clear description
Steps to reproduce
Expected vs actual behaviour
Operating system and version
Relevant logs

Code review#

As a reviewer#

Check:

The code works
It follows the guidelines
It has tests
It is documented
It introduces no regressions
Performance is acceptable

Constructive comment:
❌ “This is wrong”
✅ “Consider using X instead of Y because…”

As an author#

Answer all the comments
Do not be defensive
Make the changes if they are improvements
Explain your reasoning if you disagree
Thank people for the feedback

Licence#

Every contribution must be compatible with the project licence.

See LICENSE in the project root.

Expected behaviour#

Code of conduct#

We are committed to keeping a respectful environment:

Be respectful towards other contributors
Accept constructive criticism
Focus on the code, not the person
Respect privacy
Report abuse

If you see inappropriate behaviour#

Contact the maintainers directly (privately).

Recognition#

Contributors will be credited in CONTRIBUTORS.md
Commits stay in the Git history
Major releases may have a special changelog

Help and support#

Questions about contributing#

Open a Discussion on GitHub
Ask in the community chat (if there is one)

Do not know where to start#

Look for issues with these labels:

good-first-issue - For new contributors
help-wanted - Help wanted
documentation - Documentation improvements

You need help#

Mention maintainers with @
Be specific about your question
Share code/error output if relevant

Changes we do not accept#

❌ We do not accept:

Code that breaks compatibility without a major version
Changes that require proprietary libraries
Code that has no tests
Incomplete documentation
Style changes with no functionality
Huge commits with no description

✅ We accept:

New features that are well tested
Bug fixes
Performance improvements with evidence
Improved documentation
Refactoring that improves maintainability
Additional tests

Maintenance#

If you are a maintainer#

Responsibilities:

Review PRs promptly
Keep the code clean
Update the documentation
Moderate behaviour
Plan releases

Merging#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Before merging, check:
git checkout main
git pull origin main
git merge --no-ff feature/branch -m "Merge feature/branch"

# Resolve conflicts if there are any

git push origin main

# Delete the branch
git push origin --delete feature/branch

Releases#

Versioning: MAJOR.MINOR.PATCH

MAJOR - Breaking changes
MINOR - New features
PATCH - Bug fixes

Next steps#

Pick an issue or feature
Comment that you will be working on it
Follow this contribution process
Thanks for contributing!

Resources#

Frequently asked questions#

Q: Can I work on several things at the same time? A: Use a different branch for each thing.

Q: How long does it take to review my PR? A: It depends, typically 1-3 days.

Q: What if my PR is rejected? A: The reasons will be explained. You can ask for clarification.

Q: Can I commit directly? A: No, everything goes through a PR (maintainers included).

Q: Where do I see my contributions? A: On your GitHub profile and in git log.

Thanks for considering contributing to Vasak Desktop! 🎉

← Previous

Debugging

Code guidelines | vasak-desktop