We want to make contributing to this project as easy and transparent as possible.
If you want to contribute a bug fix or feature to lurk, here's how to proceed:
- Fork the repo and create your branch from
master. - If you've added code that should be tested, add tests.
- If you've changed APIs, update the documentation.
- Ensure the test suite passes.
- Submit your pull-request, writing a clear description of its intended purpose, and linking any issues it addresses
The maintainers will review your pull request as soon as they can, and it can only be merged once it has at least one approval . The comments can be in several forms:
- 'Comment' usually indicates the reviewer doesn't yet commit to approving your code but has important remarks to contribute.
- 'Request Changes' means changes need to be made before the reviewer approves at all.
- 'Approve' can be of two forms depending on the exact nature of the comments:
- Approval with no restrictions, or non-blocking comments indicates this can be merged by a maintainer.
- Approval with explicitly marked blocking comments means: "I don't need to review this again, but I need you (and trust you) to fix these issues first."
A pull-request must meet certain criteria before it can be merged.
- If you are fine with a squash merge, your pull-request's final commit should have at least one approval from a reviewer, and from all maintainers listed in the .github/CODEOWNERS file for the touched code sections.
- If you prefer a classic merge, the pull-request should meet the above conditions, and and it should be a fast-forward merge from master, which implies it must also be up-to-date.
Warning: An up-to-date, rebased branch is required for a fast-forward merge. This means that your branch should not contain any merge commits: while we do not object to Merge as a pull-request merge method, we prefer the pull-request's history to be linear. To achieve this, you can update your local branch with git pull --rebase (see doc).
A maintainer will merge your pull-request (or their own) using one of the following methods:
- The GitHub's merge queue with a squash merge strategy. This is the simplest workflow and always acceptable if you don't mind having a single commit.
- If your commit history is carefully cleaned to remove unnecessary commits and ensure that each retained commit is meaningful, a repo admin may use the 'Merge' strategy.
Please feel free to specify your preferred merge method in your PR summary.
The implemented workflow is represented below, with rounded corners and dotted lines automatically handled by Github's merge queue:
flowchart TD
Review{Is *last commit* of PR reviewed by CODEOWNERS?} -->|Yes| Squash
Review --> |No| GReview[Get fresh review]
GReview --> Review
Squash{Are you OK with Squash merge?} -->|Yes| MQueue(Merge queue)
Squash --> |No| Update{Is PR Up to date?}
Update --> |Yes| Merge[Get a maintainer to merge it for you!]
Update --> |No| Rebase[Rebase & get fresh review]
Rebase --> Review
Merge --> |It worked| Celebrate
Merge --> |Somebody pushed to master before maintainer| Rebase
MQueue -.-> |PR squash-merges cleanly on master & passes CI| Celebrate
MQueue -.-> |Github merge queue found squash-merge or CI issue| Rebase
Note: In exceptional cases, we may preserve some messy commit history if not doing so would lose too much important information and fully disentangling is too difficult. We expect this would rarely apply.
We use GitHub issues to track public bugs. Please ensure your description is clear and has sufficient instructions to be able to reproduce the issue.
By contributing to lurk-lang, you agree that your contributions will be licensed under both MIT and Apache 2.0 licenses.