|
| 1 | +### mesa-amd dev and uprev process |
| 2 | + |
| 3 | +mesa-amd follows a traditional [cros_workon](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/developer_guide.md#making-changes-to-packages-whose-source-code-is-checked-into-chromium-os-git-repositories) workflow where changes are made directly to src/third_party/mesa-amd. This is different from the [mesa](https://chromium.googlesource.com/chromiumos/overlays/chromiumos-overlay/+/HEAD/media-libs/mesa/mesa-9999.ebuild) project, which follows the CROS_WORKON_MANUAL_UPREV workflow. |
| 4 | + |
| 5 | +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](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/kernel_development.md#commit-messages-summary-lines-chromium_upstream_fromlist_backport) as changes in the kernel and elsewhere in Chrome OS. |
| 6 | + |
| 7 | +Refer to the [upstream documentation](https://docs.mesa3d.org/releasing.html#release-schedule) for details about upstream mesa's release schedule. To summarize, approximately every three months is a [feature release](https://docs.mesa3d.org/releasing.html#feature-releases), followed by [stable releases](https://docs.mesa3d.org/releasing.html#stable-releases) approximately every two weeks. |
| 8 | + |
| 9 | +mesa-amd generally tracks upstream feature release branches, with possibly a small number of downstream changes applied on top. |
| 10 | + |
| 11 | +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](https://chromium.googlesource.com/chromiumos/third_party/mesa/+/refs/tags/upstream/mesa-21.2.1) and [upstream/21.1](https://chromium.googlesource.com/chromiumos/third_party/mesa/+/refs/heads/upstream/21.2)). |
| 12 | + |
| 13 | +#### Uprev process |
| 14 | + |
| 15 | +When uprevving to a new release branch, follow the below process to reset the tree to its upstream state. |
| 16 | +``` |
| 17 | + # Create a merge commit that resolves all merge conflicts such that all changes are discarded in favor of those in the new upstream branch |
| 18 | + git merge upstream/mesa-21.2.1 -X theirs --no-commit |
| 19 | + git read-tree upstream/mesa-21.2.1 |
| 20 | + # Restore this file to ensure that presubmit checks survive the uprev. |
| 21 | + git add PRESUBMIT.cfg |
| 22 | + # Create an appropriate commit message, and add BUG= and TEST= tags appropriately. |
| 23 | + git commit -m "CHROMIUM: Reset tree to upstream/mesa-21.2.1" |
| 24 | + # Clean up the index |
| 25 | + git clean -f |
| 26 | + git reset --hard HEAD |
| 27 | + # Confirm that the state of the tree is identical to the upstream state, modulo the PRESUMBIT.cfg that was added. |
| 28 | + git diff-tree --no-commit-id --name-status upstream/mesa-21.2.1 HEAD |
| 29 | +``` |
| 30 | + |
| 31 | +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. |
| 32 | + |
| 33 | +Subsequent stable releases from upstream can be applied by using `git merge` and uploading the merge commit to Gerrit. |
| 34 | + |
| 35 | + |
| 36 | +#### Downstream changes |
| 37 | +The preferred flow to get changes into mesa-amd is to: |
| 38 | +1. Send a change upstream for review |
| 39 | +2. Get it merged upstream |
| 40 | +3. Ensure it is included in the next upstream stable release |
| 41 | +4. `git merge` the next stable release containing the change. |
| 42 | + |
| 43 | +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: |
| 44 | +- UPSTREAM: Indicates that the patch has landed in upstream mesa |
| 45 | + - This is appropriate when the UPSTREAM change will never land in a subsequent stable release, or we need to land it in Chrome OS more expediently than the upstream stable release process allows for. |
| 46 | + - Use `git cherry-pick -x` to ensure that the commit message contains the commit hash of the UPSTREAM commit |
| 47 | +- BACKPORT: Same as upstream, but there are conflicts that needed to be addressed |
| 48 | + - Describe the conflicts and their resolution in the commit message |
| 49 | +- FROMLIST: The patch is under review in an upstream merge request |
| 50 | + - These should not be merged except for P0/P1 issues. It's strongly preferred to wait for the completion of the review upstream, and then apply the change as UPSTREAM |
| 51 | + - Owner+Reviewer of this change is responsible to follow up on the upstream review process and ensure that it gets merged in a timely manner. |
| 52 | + - Include a link to the merge-request in the commit message |
| 53 | +- CHROMIUM: The patch cannot be upstreamed |
| 54 | + - There must be strong justification for why an upstreamable solution is not viable. |
0 commit comments