Thank you for contributing! This guide outlines the development workflow, contribution standards, and best practices when working in the super-repo.
git clone https://github.com/ROCm/rocm-systems.git
cd rocm-systemsTo limit your local checkout to only the project(s) you work on and improve performance with a large codebase, you can configure sparse-checkout prior to cloning:
git clone --no-checkout --filter=blob:none https://github.com/ROCm/rocm-systems.git
cd rocm-systems
git sparse-checkout init --cone
git sparse-checkout set projects/rocprofiler-sdk shared/rocprofiler-compute
git checkout develop # or the branch you are starting fromThis uses Git’s partial clone feature (--filter=blob:none) to reduce how much data is downloaded, and sparse-checkout to limit what is checked out to disk. For more background, including guidance on tree-less clones (--filter=tree:0) and shallow clones (--depth=1), see GitHub’s blog post on partial and shallow clones.
With the source tree as of June 19th, 2025, the clone command lasted 4 seconds in one test run. The checkout command of the two projects lasted less than 90 seconds.
If your work involves changing projects or introducing new projects, you can update your sparse-checkout environment:
git sparse-checkout set projects/hip projects/clr projects/hip-testsThis keeps your working directory clean and fast, as you won't need to clone the entire super-repo.
.github/: CI workflows, scripts, and configuration files for synchronizing repositories during the migration period.docs/: Documentation, including this guide and other helpful resources.projects/<name>/: Each folder corresponds to a ROCm library that was previously maintained in its own GitHub repository and released as distinct packages.shared/<name>/: Shared components that existed in their own repository, used as dependencies by multiple libraries, but do not produce distinct packages in previous ROCm releases.
Further changes to the structure may be made to improve development efficiency and minimize redundancy.
There were two major styling change commits, which impacted almost every C++ file in the repository. If you want to avoid seeing those changes in git blame output, you can run git config blame.ignoreRevsFile .git-blame-ignore-revs. This will exclude style changes from git blame.
You can continue working inside your project's folder as you did before the super-repo migration. This process is intended to remain as familiar as possible, though some adjustments may be made to improve efficiency based on feedback.
cd projects/hipblaslt
# Edit, build, test as usualTo stay up to date with the latest changes in the super-repo:
git fetch origin
git rebase origin/developAvoid using git merge to keep history clean and maintain a linear progression.
A mirror of this super-repo will be on GitHub Enterprise Managed User (EMU) and available only on the AMD intranet. Please reach out within the AMD intranet if you need the link and permissions.
A primary development branch will be created for a new product or new technology.
This branch will remain private until it is cleared to be shared to the public, where it be pushed to the public repo and merged with develop.
It will have a subset of CI/CD in place, relative to the public repo.
There will be automation setup to regularly to rebase the branch in the EMU repo with latest develop from the public repo.
We are transitioning to trunk-based development, with the tentative plan happening after the next major version release (7.0).
Until the switch is fully implemented, we will continue to sync changes to individual repositories following their existing development model (e.g., develop -> staging -> mainline -> release).
However, once trunk-based development is in place, feature branches will be created directly from the default branch, develop.
During this period, a high priority will be placed on keeping the develop branch healthy.
When creating a branch for your work, use the following convention to make branch names informative and consistent: users/<github-username>/<branch-name>.
Try to keep branch names descriptive yet concise to reflect the purpose of the branch. For example, referencing the GitHub Issue number if the pull request is related.
The build and test infrastructure has some tasks where pull requests from forks have fewer privileges than pull requests from branches within this repo. Thus, branches in this repo are encouraged but you are welcome to use forks and their potential gaps. We are actively working towards achieving feature parity between pull requests from branches and pull requests from forks. Please stay tuned.
Once you're ready:
git push origin branch-name-like-aboveThe super-repo uses automation to assign labels and reviewers based on the changed files. Reviewers are designated via the top-level CODEOWNERS file.
Existing testing and CI infrastructure will be updated to directly point to the super-repo. Specific checks will become mandatory for pull requests before merging. Initially, these will be limited to compilation, but will expand to correctness tests and eventually performance tests. Hardware and operating system coverage will also expand for these checks over time. Please refer to this documentation for further details on the current signals that will be provided through CI for pull requests and commits.
Data Version Control is the system for large file storage in this super-repo. It provides staging capabilities on top of what Git LFS typically provides that ROCm CI/CD workflows can make use of. Files are stored in an AWS S3 bucket that has public-read access.
Currently, dvc utilization is limited to the pal libraries in the shared/amdgpu-windows-interop directory.
If your development does not involve these files, you do not need to install dvc.
dvc can be installed as a python module via pip and is cross-platform. Visit the dvc installation page if you want to use another method of installation. Due to our use of an AWS S3 bucket with dvc, the dvc[s3] module should be installed. The configuration to download the large files from the AWS S3 bucket is already set in this repository.
pip install dvc[s3]git pull
dvc pullgit checkout feature-branch
dvc checkoutWrite-access requires authentication. Please reach out to a project lead for credentials. To make updates to files maintained by DVC:
dvc add [path-to-large-file-modified]
dvc push
git status
git add [dvc-files-mentioned-from-status-output]
git commit -m "commit message"
git pushIn order to achieve the goal of keeping the develop branch healthy, a team of ROCm engineers will be dedicated towards monitoring and triaging issues that arise.
This team will collaborate to identify offending commits to isolate what changes need to be reverted.
There may be occassions where bulk reverts may need to occur for more complex issues.
See docs/gardening.md for more information.
As this super-repo continues to evolve, weekly office hour sessions with a wide audience of ROCm engineers and managers will occur. Focused meetings with smaller project teams will be also be scheduled regularly. These discussions can go over any topic of the super-repo important to the different teams. If you want to be looped into these syncs, please reach out to project leadership.
TheRock is our new open-source build system for ROCm. It is designed to significantly enhance our support and scalability for ROCm 7.0 and beyond, and it is actively welcoming community contributions. TheRock currently supports a subset of AMD GPU targets, with ongoing efforts from our team and the community to expand this further, as detailed in TheRock roadmap.
As part of this mono-repo, TheRock is leveraged to extend our CI to add faster support for more testing and more targets with faster builds speeds. While some of these improvements will be seen with the existing CI, some will be exclusive with the TheRock CI targets given the changes in the high-level CMake system and specific patches that still remain within TheRock. Post ROCm 7.0, our goal is to unify our build system to one to ensure all of our CI has the benefits of the new build system.
Happy contributing!