Code Aurora Forum (CAF), a collaborative open source project at The Linux Foundation, hosts tested open source software code needed to provide open source and upstream enablement for innovative, performance optimized, network connectivity and related ecosystems to support system on a chip (SoC) products. It also serves as a staging area for open source code that is submitted to various upstream projects such as the Linux kernel and Android. CAF also mirrors key upstream projects for use by the community. CAF uses git as “the stupid content tracker”.
It is important to note that only open source software is hosted on CAF. Proprietary software and pre-built executable binary artifacts (e.g. object code, shared libraries, bytecode, or firmware) do NOT belong on CAF. An exception is made for firmware binaries that are provided for convenience that follow the kernel.org linux-firmware guidelines.
The Linux kernel, Android, OEM wireless handsets, tool chains such as The LLVM Compiler Infrastructure and license identifier scan tools are some of the areas using code from CAF.
All open source software hosted on CAF Public Projects and CAF@github Projects is freely available for download – membership and/or registration on CAF is not required.
Open Source projects are listed here and here. Project Admins are the maintainers of their respective projects and provide the relevant needed info for their project in the project’s wiki or README file.
Please use https rather than SSH to clone the public repositories. CAF public mirrors use geo-IP based DNS servers to direct default requests to the nearest server.
General technical support in the CAF environment is available 24/7/365 by submitting email to .
You must be a member to create CAF projects and commit code to CAF. Approved developers and release engineers should register and create an account only after they have reviewed open source best practice guidelines. Note: please work with your Trusted Advisor on confirming approval before registering.
Members of CAF can request support for new open source project creation, adding additional repos to projects, mirroring of third-party repositories and public projects, creating SSH keys, updates to project permissions and get help with general technical support in the CAF environment by submitting email to .
Contributing members should ensure they adhere to open source best practice guidelines, license compliance and code review to ensure the quality, consistency and appropriate due diligence of open source software code being committed to CAF. It is considered good practice to establish a relationship with a Trusted Advisor or Compliance Officer, possibly within your developer community or company, who would be responsible to ensure open source software compliance prior to committing code to CAF.
- Facilitate processes to handle Open Source the right way by providing best practice guidelines and/or pre-requisite training for developers and release engineers
- Work with software developers to get their code through an approved vetting process in a timely manner
- Assist developers in the creation of documentation necessary to gain acceptance of their software into the software baseline
- Work with various stakeholders to obtain permission to release software under appropriate open source license
- Work with development teams to meet their needs and ensure process consistency across open source projects
- Help define, implement and track processes to ensure compliance with Open Source policies
Once you confirm approval with your Trusted Advisor, you should use your Company identity/email to register as a developer on CAF. Upon successful registration and after receiving prior approval by your Trusted Advisor, you will receive your CAF email – use of this CAF email will identify you as a CAF Member. Registered developers should work with their Trusted Advisor or relevant Compliant Officer on appropriate email usage.
Often, CAF project/area hierarchies reflect the structure of repositories on an internal git server that a developer may already use, although that structure is not mandatory. Developers should select an overall hierarchy prior to creating new repositories or mirroring third-party repositories on CAF so that the hierarchy reflects the long-term desired structure for the project.
To request a new CAF project/area where you can push your open source contributions, please see Project Requirements. Once the project info is received, ITPeople will open a ticket to set up your project, your wiki template and configure your permissions. Please be sure to use your appropriate email identity when communicating with ITPeople.
Note that when a new repository is created on CAF it will not be visible until you have pushed content to that repository.
Please send email to ITPeople AT codeaurora DOT org with the following information:
- Your Name
- Your Email Address
- Your CAF ID (login ID)
- Your SSH-Key fingerprint (NOT your SSH key)
- The Repo/Project Path URL
- Be sure to Cc: the Project Admins for approvals
The first step towards making open source contributions/modifications to an upstream or CAF project is to typically mirror the upstream project to the appropriate project on CAF. Your mirroring request should first be vetted by your Trusted Advisor. Once approved, the Project Admin for the respective project should send the email request for the mirroring setup to ITPeople AT codeaurora DOT org. ITPeople will then set up the mirror. Please use the following mirror request format for consistency:
- CAF Project: The project name on CAF for this request
- URL mirrored from: The URL for the external site to be mirrored
- URL to CAF git project: The path where the code will be mirrored to
- Re-synced: Frequency of mirror re-sync (daily, weekly, one-time)
- POC: Contact name and email (be sure to use your appropriate identity)
- Approval Reference: URL of approved Trusted Advisor ticket or email copy of approval
Once the mirror is setup, the developer should be able to mirror the CAF repo to an internal server repo and begin making modifications on top of the upstream baseline.
Push to CAF is defined here as the act of pushing open source code to a pre-determined repo on an existing project at CAF. To provide assurance of the code provenance of all hosted code for a CAF project, the Linux Foundation recommends bringing in existing codebases through a code review system as historical commits could contain non-compliant code not present in the latest commit.
Note that when a new repository is created on CAF it will not be visible until you have pushed content to that repository.
Every project on CAF has a Project Admin who authorizes the write permissions with ITPeople for their respective project and repos. If you are requesting push access to an existing project or repo, you will need authorization and approval from the respective Project Admin. These project and repo access permissions will be stored and managed in a git config file for access by ITPeople.
There are pre-requisites and several steps in this process as follows.
- Relevant roles for Trusted Advisor and Release Engineer for the project have been established and approved (see above reference )
- Completion of relevant training for CAF distribution process
- Write permission approval and set up has been completed by ITPeople
- OSS Code has been vetted and approved by the project’s Trusted Advisor
- Project has been approved and set up has been completed by ITPeople
Note that all code to be upload to CAF needs prior approval by your appointed “Trusted Advisor” or engineering team member who will be responsible to ensure your code has been appropriately vetted and approved using the following guidelines:
- Appropriate OSS license is confirmed and in compliance
- DCO (signed-off-by) or Contribution Agreement has been completed.
- Code is free of executable binary artifacts (e.g. object code, executables, shared libraries, bytecode, or firmware. An exception is made for firmware binaries that are provided for convenience that follow the kernel.org linux-firmware guidelines.)
- Code is confirmed open source
- Your Trusted Advisor has approved the release
Once approval has been confirmed, code is ready to be pushed to CAF. Below can be used as reference:
git clone <internal_git_server>/<internal_repository_name> -b <internal_branch_name>
# Note the caret (^) after the approved_git_tag. This is Git’s way of dereferencing a tag to the commit ID that it points to.
git push ssh:~/~/email@example.com:22/<CAF_area>/<CAF_repository_name> <approved_git_tag>^:refs/heads/<CAF_branch_name>
git push ssh:~/~/firstname.lastname@example.org:22/<CAF_area>/<CAF_repository_name> <approved_git_tag>
In Git 1.7.0 and later, you can check out a new branch:
git checkout -b <branch>
Edit files, add and commit. Then push with the -u option:
git push -u origin <branch>
Note that “CAF_area” is the project/area where the repository resides on CAF. Also, the internal and CAF repository names may be the same as well as the internal and CAF branch names. However, this is just a matter of convenience and not a requirement.
You may want to consider using automation and service accounts if you need to regularly commit code to CAF.
If you are moving a repository from an existing location, you will need to add the CAF remote to your local clone of that repository.
To do that, add the remote using the git command line:
git add remote email@example.com:external/<CAF_area>/<CAF_repository_name>
Then you will be able to push existing branches/tags to this remote, for example:
git push -u <remote_name> <branch_name>
If CAF is the new home for this source code, you should probably do a fresh clone from codeaurora.org and start working in that new location so everything is setup properly.
Alternatively this can be done without adding a local remote, by pushing directly to the URL:
git push firstname.lastname@example.org:external/<CAF_area>/<CAF_repository_name> <branch_name>
If you want to push to a differently named branch than the original repository:
git push email@example.com:external/<CAF_area>/<CAF_repository_name> <old_branch_name>:<caf_branch_name>
The Project Admin should email ITPeople AT codeaurora DOT org and ask for the project to be made public. There are many options of how this could be done, but these are the three most commonly used:
- projects/repos are made public in the same location they existed as private
- projects/repos are moved to a new location to be made public
- project owners can push the private commits to a public repo to make them public
After the second two options, the private locations should then be removed after all commits are confirmed to exist in the public location.
*GitHub-specific instructions for onboarding codebases*
1. After ITPeople creates a given repository and sets up permissions under the CAF Org, an initial committer can fork the repository to their own account.
2. Clone the repository locally, which will contain an initial commit. We recommend at this point you create a topic branch locally, rather than working directly off the master branch.
3. You will need to copy or rebase your incoming code into the repository and commit it. Either way, the commit(s) must pass code provenance requirements:
- must have a DCO signature in the commit message (git commit -s),
- must use compliant licenses, and
- may not contain any executable binary artifacts (e.g. object code, executables, shared libraries, bytecode, or firmware). An exception is made for firmware binaries that are provided for convenience that follow the *kernel.org linux-firmware guidelines.
* Copying the working directory is the most straightforward, and does not bring in any history. Make sure to copy all files including hidden files (files starting with “.”). Add and commit the files with a DCO sign-off.
* History can be brought in via rebasing or cherry-pick the entire history, provided the above conditions are met, but this process is more involved and left as an exercise for the committer. Note, regardless of how this is done, the commits hashes will not match earlier versions of the repository.
4. Push the code to the corresponding topic branch on your GitHub fork.
5. Create a pull request from your topic branch to the master branch on project’s repository, which will validate the commit(s) with a DCO check and any CI verify jobs in place.
6. Someone other than that contributor will have to review the pull request and merge it, as we enforce independent reviews on all contributions.
A good command for testing access:
ssh firstname.lastname@example.org info <CAF_area>/<CAF_project>/<CAF_repo_name>
hello <CAF_username>, this is git@pdx-caf-gitolite running gitolite3 3.6.6-1.el6 on git 2.13.2
R W <CAF_area>/<CAF_project>/<CAF_repo_name>
You can push between branches of different names, by substituting