We're happy you're interested in Landr!
Community contribution is greatly encouraged and appreciated. Use the following guidelines to successfully and sustainably contribute your hard work to take landr to the next level.
As a first step, make sure to take a look at the architecture document, which describes how Landr works.
The main areas we would love to get your help with are:
Have you seen open source projects adopting a new convention that would allow us to understand the project better and produce better websites? Let us know, or even better: make Landr understand them!
Each project is unique, and the parts that Landr can infer out of the box change depending on the project. We want to consider all these combinations and create adaptative websites no matter what subset of information we have.
The best way to test this is by attempting to run Landr on any of your projects, and checking if the results are not satisfactory.
Landr uses the OpenEmbedded commit conventions. We also require a
Change-type footer tag that is either
major, depending on the change your patch makes in terms of Semantic Versioning.
We enforce certain rules on commits with the following goals in mind:
CHANGELOG.mdwithout any human intervention.
Our CI will run checks to ensure this guidelines are followed and won't allow merging contributions that don't adhere to them. Version number and changelog are automatically handled by the CI build flow after a pull request is merged. You only need to worry about the commit itself.
Each commit message should consist of a header a body and a footer, structured in the following format:
<scope (optional)>: <subject (mandatory)> --BLANK LINE-- (optional) <body> --BLANK LINE-- (optional) Connects-to: #issue-number (mandatory) Change-type: major | minor | patch (optional) Signed-off-by: Foo Bar <email@example.com>
scope: If your commit touches a well defined component/part/service please addthe scope tag to clarify. Some examples:
subject: The subject should contain a short description of the change. Use the imperative, present tense.
body: A detailed description of changes being made and reasoning if necessary. This may contain several paragraphs.
Connects-to: If your commit fixes or is connected to an existing issue, link it by adding this tag with
Change-type: At least one of your commits on a PR needs to have this tag. You have the flexibility, and it's good practise, to use this tag in as many commits as you see fit; in the end, the resulting change type for the scope of the PR will be folded down to the biggest one as marked in the commits (
major>minor>patch). Our version numbering adheres to Semantic Versioning.
Signed-off-by: Sign your commits by providing your full name and email address in the format:
Name Surname <firstname.lastname@example.org>. This is an optional tag.
Here are some examples of valid commits:
Big new feature
multi-room: Add multi-room feature This feature adds multi-room audio streaming to balenaSound. No breaking changes were made, but considering this a major version bump since it's a big feature and all services were affected. New services added: - snapcast-server - snapcast-client - fleet-supervisor Other changes: - By default, all audio services now stream to a fifo pipe file instead of alsa backend. - Multi-room can be disabled via env var DISABLE_MULTI_ROOM. Change-type: major Signed-off-by: Tomás Migone <email@example.com>
Remove mplayer, use WAV notification sounds Change-type: patch Signed-off-by: Chris Crocker-White <firstname.lastname@example.org>
Fix an issue
Fix spotify password error if it has spaces Change-type: patch Connects-to: #90
Pull requests are the only way of pushing your code to the
master branch. When creating a PR make sure you choose a short but sensical PR title and add a few lines describing your contribution.
The PR will only be able to be merged only after:
If your PR contains multiple commits you might be asked to rebase your PR branch on top of the latest
master and squash your commits before merging. This can be achieved with the following steps, assuming that the current branch is that to be merged to master in your local file system:
git checkout master git pull git checkout your-branch git rebase -i master
At this point
git rebase will prompt you to choose an action for each commit and resolve any conflicts. You should
pick one commit,
reword it if necessary and
squash the rest. The reason behind using rebase is that it makes for tidier git branching history. Push the rebased PR branch to the remote and you should be good to go:
git push --force-with-lease origin your-branch
We strongly encourage using the
--force-with-lease option instead of
--force when performing git push to a repository. The reason is that
git push --force can accidentally overwrite work that has been pushed by a team member in the meantime.
If for some reason it looks like the checks and tests for the PR have failed, add a comment to the PR with
@balena-ci retest. This should force balenaCI to re-run all the tests again. Balena CI
Landr makes use of Balena's internal CI system which not only runs the tests, but automatically generates a CHANGELOG based on your commits and their corresponding
You may run the test suite with the
npm test command. We enable code coverage support, and you can see the report after running the tests by opening
coverage/index.html in your browser.
This project makes use of EditorConfig. Make sure your editor supports it so that it doesn't deviate from indentation, line endings, and other text related conventions.