commit | 660c1720564860fbfe65fa79cff242789450bd17 | [log] [tgz] |
---|---|---|
author | Andrew Lamb <andrewlamb@chromium.org> | Thu Mar 19 18:31:25 2020 |
committer | Commit Bot <commit-bot@chromium.org> | Thu Mar 19 19:28:47 2020 |
tree | 224bf14b22e6768908a940ae667fe4efb8c911aa | |
parent | a27b69c663f39f05583228844a4d39d418f0e2b5 [diff] |
Add note on Cq-Depends to README. - See bug / README section on why Cq-Depends can't work across project repos. This has been confusing for contributors. BUG=chromium:1061439 TEST=None Change-Id: I1379aa3ce63b730cbc79381c2f3cbc94615fec9d Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/config/+/2110313 Commit-Queue: David Burger <dburger@chromium.org> Tested-by: Andrew Lamb <andrewlamb@chromium.org> Auto-Submit: Andrew Lamb <andrewlamb@chromium.org> Reviewed-by: David Burger <dburger@chromium.org>
Before beginning verify that you have appropriate permissions to work with the project. This will usually mean having membership in the partner domain account that is configured for your project. Inquire with your local representative or Google contact if you need more information about the partner domain accounts configured for your project.
Follow the Chromium OS Quick Start Guide through to the end of the “Get the Source” section. This guide walks you through installing prerequisites and syncing the public Chromium OS source code into a $SOURCE_REPO directory. This step pulls down a lot of code and could take up to an hour.
Verify the name of your $PROGRAM and $PROJECT with your local representative or Google contact. These values will be used in the command below.
Run the following command to sync your $PROGRAM and $PROJECT from within your chromiumos checkout in the $SOURCE_REPO/src/config directory:
./setup_project.sh $PROGRAM $PROJECT
This command will execute a number of steps including checking out your program and project and other related repositories, symlinking a local manifest, and finally doing a full chromiumos sync.
The $SOURCE_REPO/src/config/bin directory contains utilties for working with your project. Add the directory to the end of your PATH. You will probably want to add this configuration in your ~/.bashrc file or other appropriate location so you don't have to repeatedly set the PATH:
export PATH=$PATH:$SOURCE_REPO/src/config/bin
If you got to this point without an error you are set up to start working on your project.
After setting up your project you'll want to note the location of several important repositories within the checkout:
Partners will rarely propose changes to src/config and occasionally propose changes to src/program/$PROGRAM. The bulk of a partner's work will occur in in src/project/$PROGRAM/$PROJECT.
Configuration changes are made to a project by adjusting the Starlark configuration definition in $SOURCE_REPO/src/project/$PROGRAM/$PROJECT/config.star and then running the gen_config script (added to the PATH above). An example session updating project configuration follows:
cd $SOURCE_REPO/src/project/$PROGRAM/$PROJECT/ $EDITOR config.star # Adjust contents of config.star and save. gen_config config.star
This will cause the generation of configuration payloads that can be found at:
These files represent the same configuration, one is in binary format and is used in production. The binary format is more flexible and allows easier evolution of the schema. The second is in text format. The text format is intended to allow the user to easily eyeball the effects of changes.
To submit the changes the user first commits the files and then submits them to commit queue (CQ):
git add . git commit # Add commit message with BUG= and TEST= directives repo upload .
This will result in a reviewable CL in gerrit. The exact URL will for your CL will be output when the CL is uploaded. The CL will need to be approved and pass CQ. Details on working with CLs and the progression through review and CQ can be found in the Chromium OS Contributing Guide and more specifically in the Going through review section. CQ verifies that you have correctly generated your configuration payload and that you have not violated the program's constraints.
For security and privacy, the CQ verifiers that check config changes are only given read access on a specific project. For example, a verifier checking the config of project1
cannot read the repo containing project2
's config. This means that Cq-Depends
groups affecting multiple projects are not allowed.
In the above example, say project1
and project2
are both under programA
, and a Cq-Depends
group contains changes to project1
and programA
. The change to programA
can potentially break project2
's config, so the CQ verifier for project2
must be run; however, this CQ verifier does not have read access on project1
's config, so it will fail to read the change to project1
.
Since the CQ verifiers only need to checkout a small subset of repos and run checks on configs, their total runtime should be less than 5 minutes, making Cq-Depends
less nececessary.