Contributing

Contributing to Balean OSS

First off, thanks for taking the time to contribute! 🎉

This document explains how to submit bug reports, request features, and propose code changes to a project in the Balean open source software group on GitLab. It is meant to be read alongside our Code of Conduct, which applies to all contribution channels.

People contributing to Balean or Vortex are considered volunteers to Balean so we encourage them to read the community guide as well.

Table of Contents

1. Ways to Contribute
2. Getting Help
3. Setting Up a Development Environment
4. How to Submit a Bug Report
5. How to Suggest a Feature
6. Submitting Code Changes
7. Style Guidelines
8. Review Process
9. Recognition

Ways to Contribute

You don’t have to write code to help. We welcome:

• 🐛 Bug reports — spotting and clearly describing broken behavior
• 💡 Feature ideas — proposals for new functionality or improvements
• 📝 Documentation — fixes, clarifications, examples, translations
• 🧪 Tests — more coverage, especially around edge cases
• 🔍 Code review — feedback on open pull requests
• 📢 Outreach — blog posts, talks, or telling others about the project

Handbook updates

If you want to help improve our handbook, please also read our Handbook Contributing guide.

Documentation updates

It is also possible to contribute as a technical writer to our documentation.

Balean is based on a platform called Vortex. Documentation for Vortex is available online via this link: https://balean-oss.gitlab.io/vortex/docs/. Check its contributing guide as well.

Getting Help

• Community issue tracker: https://gitlab.com/balean-oss/balean-volunteering-challenges/-/work_items
• Chat: Balean’s Volunteering Community on Discord
• Discussions / Q&A: github.com/project-name/discussions

If you’re unsure whether a bug is a bug, ask in Discord first — it keeps the issue tracker focused.

How to Submit a Bug Report

Open a new issue in our community issue tracker or on one of the projects and include:

1. A clear title — e.g. “Crash when parsing an empty config file”
2. Steps to reproduce — the smallest sequence that triggers the bug
3. Expected behavior vs. actual behavior
4. Environment — OS, runtime version, and project version
5. A minimal reproduction — a repo, snippet, or failing test if possible

_Use the bug issue template for better

How to Suggest a Feature

1. Check existing features in our Community issue tracker, on the project work item list or in our roadmap — it may already be planned.
2. Open a feature request using the issue template and describe:

• the problem you’re trying to solve (not just the solution),
• how you imagine it working,
• alternatives you’ve considered.

Small, well-scoped ideas may go straight to a MR; anything that changes the public API should be discussed in an issue first.

Submitting Code Changes

Before you start: for anything non-trivial, open an issue first so we can agree on the approach. We’d hate for you to spend a weekend on something we can’t merge.

Workflow

# Keep your main branch clean; work on feature branches
git checkout -b fix/empty-config-crash

# Make your changes, keeping commits focused
git commit -m "Fix crash when parsing an empty config file"

# Keep your branch up to date
git fetch upstream
git rebase upstream/main

# Push and open a Pull Request
git push -u origin fix/empty-config-crash

Merge request checklist

• The change was discussed in a linked issue (if non-trivial)
• Tests cover the new behavior and pass locally
• Documentation is updated (README, docs/)
• Are changes to the public online documentation required? Create an MR in our public docs repo.
• The MR has a clear description and a small, reviewable diff
• Commits are squashed into logical units
• Commits must follow Conventional Commits

We target main only — never merge release branches manually.

Style Guidelines

• Code style: We use general available linting tools to check for code styles as well as markdown style.
• Naming: follow existing conventions in the codebase; when in doubt, look at nearby code.
• Tests: every bug fix should include a regression test; new features need tests for happy path and edge cases.
• Commit messages: imperative mood (“Fix crash”, not “Fixed crash”), ≤ 72 characters, with a body explaining why for non-obvious changes.
• Documentation: write for a newcomer, not an expert.

Review Process

1. A maintainer will review your PR within 14 days.
2. Reviews focus on correctness, tests, performance, and readability. Feedback is about the code, never about you.
3. Respond to review comments by pushing new commits — don’t force-push mid-review unless asked.
4. Once approved and CI passes, a maintainer merges. We typically use squash-merges.

PRs can be closed for inactivity after 30 days without a response — you can always reopen or re-submit.

License

Most of our open source software is released under the GNU lGPLv3 license.

Documents, documentation and other texts that are meant for humans, are released under the Creative Commons license CC BY-SA 4.0

By contributing to one of our projects, you agree that your contributions will be licensed under the project’s license. See the specific project for the exact license.