Contribute a Change

Thanks for your interest in contributing to Flock. Every change to Flock is contributed through something called a "patch file". This guide shows you how to contribute patch files for review.

If you're just getting started with Flock, see the setup guide to begin contributing.

Create a commit for your changes

After making whatever changes that you'd like to nest/flock/, you need to commit those changes in a single Git commit.

Open the nest/flock/ directory as your working directory:

cd my/path/nest/flock/

Commit your local changes:

git add -A
git commit -m "[Flock] - Some description of your change (Resolves #1234)"

With your changes sitting in a single commit, you're now ready to generate a patch file and submit it for review.

Submit your change for review

Once you've committed a change to Flock, locally, it's time to generate a patch file and submit it for review by the Flock team.

Generate a patch file

Flock doesn't use Git to track its changes to Flutter. Instead, Flock collects a bunch of "patch files" and replays them on top of Flutter. To contribute your changes to Flock, you first need to convert your Git commit to a patch file.

From your nest directory (not the flock directory), run the following command:

# Export your commit as a patch file.
tools/git-export-patches -o patches

After exporting patches, check your nest/patches/ directory. You should see a new patch that includes all of your changes.

Register your patch file with Nest

Nest only applies patches that are listed in its patch configuration file.

Open nest/patches/.patches and ensure that the name of your patch file appears in the list. This list should have been updated when you ran the git-export-patches script.

Create a Pull Request for review

Add and commit your new patch file to Nest.

Hypothetical example:

git add patches
git commit -m "[Flock] - Some description of your change (Resolves #1234)"
git push origin my_branch

Go to GitHub and open a Pull Request from your branch to the main Nest repository.

Include all relevant information in your PR to help with a quick and effective review.

Review your PR in Flock

Your pull request to Nest only includes a patch file. It would be very difficult to do any kind of effective code review based solely on a patch file.

When you put up your Nest PR with the patch file, the Nest repository automatically creates another PR within the Flock repository. This Flock PR is temporary - it will never be merged - but the Flock PR shows your patch file like a regular change against Flock. Reviewers can see how your changes actually impact Flock, more broadly.

Reviewers will place review comments in your Flock PR, not your Nest PR. So be sure that you keep an eye on your generated PR in Flock.

Update your PR after review

Code reviews almost always include requests for a change. When a reviewer requests a change, you need to do the following:

  1. Make changes to your local Flock version based on PR feedback.
  2. Add your updates to your existing Flock commit (don't create more Git commits).
  3. Regenerate your Nest patch file.
  4. Push your updated Nest patch file to your Nest PR.
  5. Your Flock PR will be automatically regenerated by Nest automation.

This process may need to be repeated a number of times until your PR is ready to merge.

If you're not comfortable with typical Git history management, here are two ways to ensure that your Flock changes remain in a single commit.

Option 1: Reset your previous Flock changes, create a new commit, and push the new commit.

git reset HEAD~1
git add -A
git commit -m "[Flock] - Some description of your change (Resolves #1234)"
git push -f origin my_nest_pr

Option 2: Amend your existing commit with your new changes.

git add -A
git commit --amend
git push -f origin my_nest_pr