mesa-amd follows a traditional cros_workon workflow where changes are made directly to src/third_party/mesa-amd. This is different from the mesa project, which follows the CROS_WORKON_MANUAL_UPREV workflow.
Working in mesa-amd takes an “upstream first” philosophy, and downstream changes represent technical debt and should be avoided. Commit messages for downstream changes in mesa-amd are prefixed in a similar fashion as changes in the kernel and elsewhere in Chrome OS.
Refer to the upstream documentation for details about upstream mesa's release schedule. To summarize, approximately every three months is a feature release, followed by stable releases approximately every two weeks.
mesa-amd generally tracks upstream feature release branches, with possibly a small number of downstream changes applied on top.
Tags and branches from upstream are automatically synced to the chromiumos mesa mirror. Tags and branch names are synced under upstream/... (for example, upstream/mesa-21.2.1 and upstream/21.1).
When uprevving to a new release branch, follow the below process to reset the tree to its upstream state.
# Create a merge commit that resolves all merge conflicts such that all changes are discarded in favor of those in the new upstream branch git merge upstream/mesa-21.2.1 -X theirs --no-commit git read-tree upstream/mesa-21.2.1 # Restore this file to ensure that presubmit checks survive the uprev. git add PRESUBMIT.cfg # Create an appropriate commit message, and add BUG= and TEST= tags appropriately. git commit -m "CHROMIUM: Reset tree to upstream/mesa-21.2.1" # Clean up the index git clean -f git reset --hard HEAD # Confirm that the state of the tree is identical to the upstream state, modulo the PRESUMBIT.cfg that was added. git diff-tree --no-commit-id --name-status upstream/mesa-21.2.1 HEAD
Use git log --first-parent --pretty='%h %s'
to see the list of changes since the last time the tree was reset, and assess whether downstream patches can be dropped, or if they need to be cherry-picked again. You may need to cherry-pick some long-lived dowstream changes (i.e. CHROMIUM: patches). When you cherry-pick such a patch, edit the commit message to strip old tags such as Change-Id, Reviewed-By, etc., and update the BUG= to reference the bug tracking the uprev effort.
Subsequent stable releases from upstream can be applied by using git merge
and uploading the merge commit to Gerrit.
The preferred flow to get changes into mesa-amd is to:
git merge
the next stable release containing the change.There may be cases where we cannot do this for a particular change, or a change is needed more urgently than this process allows. In such cases, we may upload changes to Gerrit with an appropriate prefix. These prefixes are:
git cherry-pick -x
to ensure that the commit message contains the commit hash of the UPSTREAM commit