Ah! Good to see you are reading this. We feel that developing a programming language without the input of our target audience is counterproductive. Therefore we gladly welcome contributions from all developers!
If you haven't already, join our discord server. We can help you get underway with the things you're most excited about.
Some important resources to get started are:
- Our roadmap gives a very broad overview of where we're heading.
- We're usually online on our discord server during business hours (UTC+1).
- Bugs? Report them on GitHub
- What is our vision on testing?
- Try to use Test Driven Development
- About snapshot tests
- Our Git workflow
- Fork in the repository
- Locally clone the fork
- Create a branch
- Synchronise your branch
- Commit changes
- Push changes
- Create a Pull Request
- Merging a Pull Request
We feel that having an extensive regression testing suite allows developers to add new features or change existing features with more confidence; knowing that changes behave the way you expect them to and without unwittingly impacting other features.
We try to implement new features using Test Driven Development (TTD). In practice this means that we write tests - based on requirements - before implementing new features to ensure that they work. This seamlessly integrates with regression testing, as there is no extra workload.
A snapshot test asserts that the output of an operation doesn't change. As such, we use it to verify that a feature generates (and keeps generating) the correct output. The insta crate is used throughout the codebase to enable this functionality. See crates/mun_hir/src/ty/tests.rs for an example.
We follow a Git workflow similar to Kubernetes. If you are not familiar with it, please review the following instructions.
- Visit https://github.com/mun-lang/mun
- Click the
Forkbutton (top right) to establish a cloud-based fork.
You should now have a fork of the Mun repo at https://github.com/$user/mun,
where $user is your GitHub handle.
To create a local clone of your fork at the $working_dir folder, execute the
following Git commands:
cd $working_dir
git clone https://github.com/$user/mun.git
# or: git clone [email protected]:$user/mun.git
cd $working_dir/mun
git remote add upstream https://github.com/mun-lang/mun.git
# or: git remote add upstream [email protected]:mun-lang/mun.git
# Confirm that your remotes make sense:
git remote -vUpdate your local main branch:
cd $working_dir/mun
git fetch upstream
git checkout main
git rebase upstream/mainBranch from main:
git checkout -b feature/my-preciousNow you are ready to edit code on the feature/my-precious branch.
# While on your feature/my-precious branch
git fetch upstream
git rebase upstream/mainPlease don't use git pull instead of the above fetch / rebase. By default,
pull uses a built-in list of strategies that result in merge commits. These
make the commit history messy and violate the principle that commits ought to be
individually understandable and useful. You can also consider changing your
.git/config file via git config branch.autoSetupRebase always to change the
behaviour of git pull to always use --rebase
merging.
Commit your changes.
git commitAlways write a clear log message for your commits. We use the Conventional Commits format, which states that a commit message should be structured as follows:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in semantic versioning). A BREAKING CHANGE can be part of commits of any type.
Recommended types are: feat, fix, ci, docs, style, refactor,
perf, test, revert or improvement.
One-line messages are fine for small changes, but bigger changes should include a body.
feat: allow provided config object to extend other configs
refactor!: drop support for Node 6
feat(lang): add polish language
fix: correct minor typos in code
see the issue for details
on typos fixed.
Reviewed-by: Z
Refs #133
For more examples, check recent commit message.
When ready to review (or to create an off-site backup of your work), push your branch to your fork:
git push $your_remote_name feature/my-preciousIf history was rewritten as a result of a rebase merge, you'll need to force push changes.
Please submit a GitHub Pull Request to
mun-lang/mun with a clear list
of changes (read more about pull
requests). When you submit a pull request,
make sure to include tests that validate the implemented feature or bugfix
(read about testing in Mun). Before committing, please confirm that your code
style is correct (using cargo fmt) and all lint warning have been resolved
(using cargo clippy). We integrated cargo-husky
as a pre-commit hook, to make this process as simple as possible.
Please consider that very small PRs are easy to review, whereas very large PRs are very difficult to review. The more focused your PR, the shorter the timeline for approval.
Once your pull request has been opened, it will be assigned to one or more reviewers. Those reviewers will do a thorough code review, looking for correctness, bugs, opportunities for improvement, documentation and comments, and style.
Please commit changes made in response to review comments to the same branch on your fork. Feel free to use GitHub's suggestions, but you'll likely have to clean up your history afterwards.
After a review, prepare your PR for merging by cleaning up the commit history. All commits left on your branch after a review should represent meaningful milestones or units of work. Use commits to add clarity to the development and review process.
Before merging a PR, squash the following kinds of commits:
- Fixes/review feedback
- Typos
- Merges and rebases
- Work in progress
Aim to have every commit in a PR compile and pass tests independently if you can, but it's not a requirement. In particular, merge commits must be removed!
To edit or squash your commits, perform an interactive
rebase. Start an
interactive rebase using a specific commit hash, or count backwards from your
last commit using HEAD~<n>, where <n> represents the number of commits to
include in the rebase.
git rebase -i HEAD~3The output looks similar to:
pick 2ebe926 feat(memory): add mark-region garbage collector
pick 31f33e9 misc: apply review suggestions
pick b0315fe test(memory): add unit test for mark-region gc
# Rebase 7c34fc9..b0315ff onto 7c34fc9 (3 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup <commit> = like "squash", but discard this commit's log message
...Use a command-line text editor to change the word pick to the appropriate
command, e.g. fixup for commits that you want to squash:
pick 2ebe926 feat(memory): add mark-region garbage collector
fixup 31f33e9 misc: apply review suggestions
pick b0315fe test(memory): add unit test for mark-region gc
...Upon a successful rebase, push your changes to the remote branch:
git push --force-with-leaseOnce your pull request has been reviewed and approved, your PR is ready for merging. Merging will automatically be taken care of by the Reviewer.