Contributing to Liquid Metal repos
Each component will have its own dedicated contribution guide along with specific environment setup instructions. (If they don't, or they are wrong, why not contribute some? 😉)
You can follow the links from the previous page
which will take you to the repos' github pages and individual CONTRIBUTING.md guides.
Here are some steps and guidelines which will apply to all, so read these first before you head off to your chosen repo 🏃♂️.
Working on your solution
Create a fork of the component repo and clone your fork. Pay attention to what the specific component's docs say about where you should clone the repo locally. You may also want to add the original repo to your remotes to keep up to date with upstream changes.
Follow the repo's instructions to set up your environment.
Run the unit tests.
Create a new branch for your work.
git checkout -b <feature-name>Write your solution, making sure you stick to repo patterns and practices.
Try to commit in small chunks so that changes are well described and not lumped in with something unrelated. This will make debugging easier in the future. Make sure commit messages are in the proper format.
Ensure that every commit you intend to be merged is compilable and that the tests run successfully at that point.
Make sure your commits are signed.
All code contributions must be submitted with unit tests. Each repo will detail or demonstrate what appropriate testing looks like.
For extra special bonus points, if you see any tests missing from the area you are working on, please add them! It will be much appreciated ❤️ .
Check any documentation and update it to cover your changes if applicable. If your change will impact the next version of the product, you will also need to update the site to describe any new user actions or API features.
Before you open your PR, run all the unit and any other tests and manually verify that your solution works.
PR submission guidelines
Push your changes to the branch on your fork and submit a pull request to the original repository
against the main branch.
Where possible, please squash your commits to ensure a tidy and descriptive history.
Make sure each commit which will be merged is compilable with the tests passing at
that point.
git push <remote-name> <feature-name>
If your PR is still a work in progress, please open a Draft PR
and prefix your title with the word WIP. When your PR is ready for review, you
can change the title and remove the Draft setting.
Our GitHub Actions integration will run any automated checks. We will review your changes and give you feedback as soon as possible.
We recommend that you regularly rebase from main of the original repo to keep your
branch up to date.
Please ensure that Allow edits and access to secrets by maintainers is checked.
While the maintainers will of course wait for you to edit your own work, if you are
unresponsive for over a week, they may add corrections or even complete the work for you,
especially if what you are contributing is very cool 🤘 .
PRs which adhere to our guidelines are more likely to be accepted (when opening the PR, please use the checklist in the template if there is one for that repo):
The description is thorough. When writing your description, please be as detailed as possible: don't make people guess what you did or simply link back to the issue (the issue explains the problem you are trying to solve, not how you solved it.) Guide your reviewers through your solution by highlighting key changes and implementation choices. Try and pre-empt any obvious questions they may have. Providing snippets (or screenshots) of output is very helpful to demonstrate new behaviour or UX changes. (Snippets are more searchable than screenshots, but we wont be mad at a sneak peek at your terminal envs 👀 .)
The change has been manually tested. If you are supplying output above then that can be your manual test, with proof 👏.
The PR has a snappy title. Your PR title will end up in the release notes, so make it a good one. Using the same rule as for the title of a commit message is generally a good idea. Try to use the imperative and centre it around the behaviour or the user value it delivers, rather than any implementation detail.
eg:
"changed SomeFunc in file.go to also do thing X"is not useful for folks stopping by to quickly see what new stuff they can do with the component, save that for commit messages or the PR description. The title"(feat): Add support for XYZ"conveys the intent concisely and clearly.There are new tests for new code. This is very much required.
There are new tests for old code in the same area! This will earn you the title of "Best Loved and Respected Contributor" 💥 😎 .
There are well-written commit messages (see below) which will make future debugging fun. (Any commits of the variety
"fix stuff","does thing"or"my god why"must be squashed or rebased.)Each of those well-written commits is compilable and the tests run successfully at that point.
In general, we will merge a PR once someone in the team has reviewed and approved it. Trivial changes (e.g., corrections to spelling) may get waved through quickly. For substantial changes, more people may become involved, and you might get asked to resubmit the PR or divide the changes into more than one PR if there is too much going on.
Commit message formatting
For more on how to write great commit messages, and why you should, check out this excellent blog post.
We follow a rough convention for commit messages that is designed to answer three questions: what changed, why was the change made, and how did you make it.
The subject line should feature the what and the body of the commit should describe the why and how. If you encountered any weirdness along the way, this is a good place to note what you discovered and how you solved it.
An example of a stellar commit message can be found here.
The format can be described more formally as follows:
<short title for what changed, <=70 characters>
<BLANK LINE>
<why this change was made and what changed>
<BLANK LINE>
<any interesting details>
The first line is the subject and should be no longer than 70 characters, the second line is always blank, and other lines should be wrapped at a max of 80 characters. This allows the message to be easier to read on GitHub as well as in various git tools.
Here is a template which you can add to your local git config which will make commit messages easy.
Reviewing PRs
The core team aims to clear the PR queue as quickly as possible. Community members should also feel free to keep an eye on things and provide their own thoughts and expertise.
High-value and/or high priority contributions will be processed as quickly as possible, while lower priority or nice-to-have things may take a little longer to get approved.
To help facilitate a smoother and faster review, follow the guidelines above. Submissions which do not meet standards will be de-prioritised for review.