Show last authors
1 = Getting Started =
3 {{toc numbered="false" scope="page"/}}
5 = What is CAF and where is the code used? =
7 [[Code Aurora Forum (CAF)>>||rel="__blank"]], a collaborative open source project at [[The Linux Foundation>>||rel="__blank"]], hosts tested open source software code needed to provide open source and upstream enablement for innovative, performance optimized, network connectivity and related ecosystems that 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>>||rel="__blank"]] and [[Android>>||rel="__blank"]]. CAF also mirrors key upstream projects for use by the community. CAF uses git as its preferred [["dvcs".>>||rel="__blank"]]
9 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 [[ linux-firmware guidelines>>||rel="__blank"]].
11 The [[Linux kernel>>]], [[Android>>]], OEM wireless handsets, Automotive, mobile computing, IoT and Security, tool chains such as [[The LLVM Compiler Infrastructure>>]] and license identifier scan tools are some of the areas using code from CAF.
13 (% id="HHowtogetstartedondownloadingcodefromCAF" %)
14 = How to get started on downloading code from CAF =
16 All open source software hosted on CAF Public Projects and repos at [[CAF@GitHub>>||rel="__blank"]] is freely available for download – [[membership>>]] in the project is not required.
18 Open Source projects are listed [[here>>]] and GitHub repos are [[here>>||rel="__blank"]]. Project Admins are the maintainers of their respective projects and provide the relevant needed info for their project or repos in the project’s wiki or README file.
20 Please use https rather than SSH to clone the [[public repositories>>||rel="__blank"]]. [[CAF public mirrors>>||rel="__blank"]] use geo-IP based DNS servers to direct default requests to the nearest server. Developers can [[configure>>]] their systems manually to direct **repo** requests to one of the servers that works best for them.
22 General technical support for CAF is available 24/7/365 via the [[CAF service desk>>||rel="__blank"]].
24 (% id="HQuick-startforCAFDevelopers2FMembers" %)
25 == Quick-start for CAF Developers/Members ==
27 **Step 1**: [[Submit>>||rel="__blank"]] your SSH key
29 **Step 2**: [[Request>>||rel="__blank"]] CAF Project setup/permissions
31 **Step 3**: [[Prepare>>||rel="__blank"]] your code
33 **Step 4**: [[Push >>||rel="__blank"]]your code (git clone/git push) to your CAF Project
35 (% id="HQuick-startfordownloadingcodefromprivaterepo" %)
36 === Quick-start for downloading code from private repo ===
38 **Step 1**: [[Request>>||rel="__blank"]] private CAF project/repo access
39 **Step 2**: Once approved, you should receive git access instructions to the email address specified in the request.
41 (% id="HCAF40GitHub" %)
42 === CAF@GitHub ===
44 CAF maintains many open source repos on [[CAF@GitHub>>]]. GitHub-specific instructions for onboarding codebases are available at the [[CAF@GitHub Support Page>>Support.Github]]. The general CAF requirements listed here also apply to the repos on CAF@GitHub.
46 (% id="HIRC" %)
47 === IRC ===
49 Please see the [[Support.IRCCloud]] for details on the IRC bouncer offered by CAF.
51 *NOTE: as of May 20 2019, ZNC services have been discontinued.
53 (% id="HPre-requisitesfordevelopers2FengineerstocontributecodetoCAF" %)
54 === Pre-requisites for developers/engineers to contribute code to CAF ===
56 Contributing members should ensure they adhere to open source [[best practice guidelines, >>]][[license compliance, >>]][[export control >>]] 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. 
58 You must be a [[member>>||rel="__blank"]] to create CAF projects and commit code to CAF. Approved developers and release engineers are granted access only after they have reviewed open source best practice guidelines. Note: please work with your company's Trusted Advisor or Compliance Officer to confirm approval //before// applying.
60 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 via the [[CAF service desk>>||rel="__blank"]].
62 (% id="HGuidelinesfortheroleofaTrustedAdvisororComplianceOfficerinanOpenSourceCommunity" %)
63 === Guidelines for the role of a Trusted Advisor or Compliance Officer in an Open Source Community ===
65 * Facilitate processes to handle Open Source the right way by providing best practice guidelines and/or pre-requisite training for developers and release engineers
66 * Work with software developers to get their code through an approved vetting process in a timely manner
67 * Assist developers in the creation of documentation necessary to gain acceptance of their software into the software baseline
68 * Work with various stakeholders to obtain permission to release software under appropriate open source license
69 * Work with development teams to meet their needs and ensure process consistency across open source projects
70 * Help define, implement and track processes to ensure compliance with Open Source policies
72 Once you confirm approval with your Trusted Advisor or Compliance Officer, you should use your Company identity/email to request access via the [[CAF service desk>>||rel="__blank"]]. Upon receiving 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.
74 (% id="HCreatingyourSSHkeyforgitpushaccess" %)
75 === Creating your SSH key for git push access ===
77 [[SSH keys>>]] are used to commit code to CAF. SSH keys offer a highly secure way of logging into a server and are best practice for authentication, allowing more security than a simple password. SSH keys are tied to your identity (your email used on CAF) so you will need to ensure you have created or submitted an SSH key that matches your identity. Partners of members who need to access code via SSH will also need to request push access via the [[CAF service desk>>||rel="__blank"]] so their SSH key can be stored in gitolite and their permissions validated with their registered identity. Partner identities should match company email.
79 **//CAF only supports 1 SSH key per user.//**
81 (% id="HCodeGuidelines--preparingyourcodeforCAF" %)
82 === Code Guidelines ~-~- preparing your code for CAF ===
84 Please remember 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 *[[ linux-firmware guidelines>>]]. 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 review system as historical commits could contain non-compliant code not present in the latest commit.
86 Contributing members are strongly encouraged to work with their Trusted Advisor/Compliance Officer to receive approval on code review guidelines to ensure the quality, consistency and appropriate due diligence of open source software code being committed to CAF.
88 CAF projects and code must include appropriate**__ marking guidelines__**:
90 * All new inbound code contributions must be made using an [[OSI-approved open source license >>||rel="__blank"]]specified for the Project within the License file
91 * All new inbound code contributions must also be accompanied by a [[Developer Certificate of Origin >>||rel="__blank"]]sign-off; more info on [[DCO >>||rel="__blank"]]
92 * All outbound code will be made available under the applicable Project license
93 * Documentation will be received and made available by the Project under the [[Creative Commons Attribution 4.0 International License>>||rel="__blank"]]
94 * If you have a signed Contributor License Agreement (CLA) that provides for copyright assignment to The Linux Foundation, please use the following format:
95 ** {{code language="shell"}}Copyright (c) {year(s)}, The Linux Foundation. All rights reserved.{{/code}}
96 * Please respect copyright attributions ~-~- DO NOT REMOVE OR MODIFY THIRD PARTY COPYRIGHT OR LICENSE MARKINGS
97 * Please work with your Trusted Advisor if you have questions regarding appropriate usage
99 (% id="HAdditionalRequirements" %)
100 ==== Additional Requirements ====
102 If you are creating a new CAF repository from scratch, we require that your repository includes:
104 * A [[README]] file that references the licenses
105 * A [[CONTRIBUTING]] file
106 * A [[Code of Conduct>>CodeOfConduct]]
108 We also strongly suggest you use some of the suggest tools to enforce these requirements.
110 * [[Repolinter>>Repolinter]] is an easy way to confirm your repository meets a set of standards
111 * [[DCO commit-msg hook>>CommitHook]] can be installed locally to enforce DCO sign off
112 * [[E-mail address pre-commit hook>>PreCommitHook]] can be installed locally to enforce using the CAF e-mail addresses for commits where applicable
114 **//*Firmware Binaries "provided for convenience"~://**
116 This is the old way firmware was included in the kernel: [[https:~~/~~/>>]] (legacy support)
118 These days, it goes in the linux-firmware repo here: [[https:~~/~~/>>]]
120 The README has some language about the restrictions: [[https:~~/~~/>>]]
122 And this file lists all the licenses for the firmware blobs: [[https:~~/~~/>>]]
124 (% id="HRequesttocreateanewCAFproject2Farea" %)
125 === Request to create a new CAF project/area ===
127 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. If your project is expected to have many repos, you may want to consider using folders to better categorize them... please see [[git repos>>]] for [[qoriq>>]] and [[imx>>]] projects for reference.
129 To request a new CAF project/area where you can push your open source contributions, please see [[Project Requirements>>||rel="__blank"]]. 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.
131 Note that when a new repository is created on CAF it will not be visible until you have pushed content to that repository.
133 (% id="HRequestaccessorpermissionstoaCAFproject2Farea" %)
134 === Request access or permissions to a CAF project/area ===
136 Please use the [[CAF service desk>>||rel="__blank"]] to request access.
138 (% id="HMirroring" %)
139 === Mirroring ===
141 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 submit a request via the [[CAF service desk>>||rel="__blank"]].
143 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.
145 (% id="HPushingcodetoaCAFProject" %)
146 === Pushing code to a CAF Project ===
148 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.
150 Note that when a new repository is created on CAF it will not be visible until you have pushed content to that repository.
152 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 CAF Project Admin. These project and repo access permissions will be stored and managed in a git config file by ITPeople.
154 There are pre-requisites and several steps in this process as follows.
156 1. Relevant roles for Trusted Advisor and Release Engineer for the project have been established and approved //(see above reference  //**__Guidelines for the role of a Trusted Advisor in an Open Source Community__**//)//
157 1. Write permission approval and set up has been completed by ITPeople
158 1. OSS Code has been vetted and approved by the project's Trusted Advisor
159 1. Project has been approved and set up has been completed by ITPeople
161 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:
163 * Appropriate OSS license is confirmed and in compliance
164 * DCO (signed-off-by) or Contribution Agreement has been completed.
165 * 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 [[ linux-firmware guidelines>>]].)
166 * Code is confirmed open source
167 * Your Trusted Advisor has approved the release
169 Once approval has been confirmed, code is ready to be pushed to CAF. Below can be used as reference:
171 **# 1. Clone the repo from your internal Git server**
173 {{code language="shell"}}
174 git clone <internal_git_server>/<internal_repository_name> -b <internal_branch_name>
175 {{/code}}
177 **# 2. Push a commit (and its ancestors) to CAF**
179 # 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. Your CAF Area is whole repo list (e.g., external/shortname that you requested in your project setup). The CAF Repository name will be the full name listed under your project; if you have a path in your repo name you will need to include the folder path in the name.
181 {{code language="shell"}}
182 git push ssh://<CAF_shortname>/<CAF_repository_name> <approved_git_tag>^:refs/heads/<CAF_branch_name>
183 {{/code}}
185 **# 3. Push a Git tag to CAF**
187 {{code language="shell"}}
188 git push ssh://<CAF_shortname>/<CAF_repository_name> <approved_git_tag>
189 {{/code}}
191 **#4. Push a branch to CAF repo**
193 In Git 1.7.0 and later, you can checkout a new branch:
195 {{code language="shell"}}
196 git checkout -b <branch>
197 {{/code}}
199 Edit files, add and commit. Then push with the -u option:
201 {{code language="shell"}}
202 git push -u origin <branch>
203 {{/code}}
205 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.
207 You may want to consider using automation and service accounts if you need to regularly commit code to CAF.
210 **#5. Push a branch from an existing repository to a new CAF repo**
212 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.
214 To do that, add the remote using the git command line (NOTE that the git@ tells it to use ssh, so the command should not need ssh://):
216 {{code language="shell"}}
217 git remote add <remote_name> ssh://<CAF_shortname>/<CAF_repository_name>
218 {{/code}}
220 Then you will be able to push existing branches/tags to this remote, for example:
222 {{code language="shell"}}
223 git push -u <remote_name> <branch_name>
224 {{/code}}
226 If CAF is the new home for this source code, you should probably do a fresh clone from and start working in that new location so everything is setup properly. 
228 Alternatively this can be done without adding a local remote, by pushing directly to the URL:
230 {{code language="shell"}}
231 git push ssh://<CAF_shortname>/<CAF_repository_name> <branch_name>
232 {{/code}}
234 If you want to push to a differently named branch than the original repository:
236 {{code language="shell"}}
237 git push ssh://<CAF_shortname>/<CAF_repository_name> <old_branch_name>:<caf_branch_name>
238 {{/code}}
240 **#6. Pushing a mirror of a repository**
242 Typically, mirroring is performed by the CAF Admins upon request, however in some cases project administrators may need to mirror a repository to CAF. If this is the case, the commands below serve as an example:
244 {{code language="shell"}}
245 $ git clone --mirror
246 $ cd upstream-repository.git
247 $ git push --mirror ssh://<CAF_shortname>/<CAF_repository_name>
248 {{/code}}
250 **#7. Pushing a patch to the patch area of a repository**
252 Make sure you have requested a patch area for your project (example:<CAF_shortname>//_patches). If that is configured you should be able to push to the master branch of your patch repository to make the new patches available in the web view.
254 {{code language="shell"}}
255 $ git push ssh://<CAF_shortname>_patches.git master
256 {{/code}}
258 (% id="HMakingaPrivateProjectPublic" %)
259 === Making a Private Project Public ===
261 The Project Admin should create a new issue on the [[CAF service desk>>||rel="__blank"]] and ask for the project to be made public. There are many options of how this could be done, but this is the most common way used:
263 * a new public project with public repos is created in a new location
264 * project owners can push the private commits to a public repo to make them public
266 After this is complete, the private locations should then be removed after all commits are confirmed to exist in the public location.
268 (% id="HTips26Troubleshooting" %)
269 === Tips & Troubleshooting ===
271 a good command for testing access:
273 {{code language="shell"}}
274 ssh info <CAF_area>/<CAF_shortname>/<CAF_repo_name>
275 {{/code}}
277 For example:
279 {{code language="shell"}}
280 ssh info external/qostg/lid
281 {{/code}}
283 corresponding output:
285 {{code language="shell"}}
286 hello <CAF_username>, this is git@pdx-caf-gitolite running gitolite3 3.6.6-1.el6 on git 2.13.2
288 R W <CAF_area>/<CAF_project>/<CAF_repo_name>
289 {{/code}}
291 You can push between branches of different names, by substituting {{code}}<branch_name>{{/code}} as {{code}}<local_branch>:<remote_branch>{{/code}}.
293 A command for getting more information on failures:
295 {{code language="shell"}}
296 ssh -T -v
297 {{/code}}
299 __Push issues__:
301 * verify you have permissions/access to the repo using the above testing access command
302 * verify that your [[SSH key is correct>>||rel="__blank"]] (and that it was not changed/updated or that you have more than 1 in your account; open an issue on the [[CAF service desk>>||rel="__blank"]] for help)
303 * verify that your IT does not [[block port 22>>||rel="__blank"]] or port 9222
304 * verify your push command is correct and using ssh (make sure you are connecting as the [['git' user>>||rel="__blank"]])
305 * verify [[APAC mirror>>||rel="__blank"]] is updating by cloning the US mirror
307 (((
308 __Clone issues__:
309 )))
311 * verify the repo is not empty (empty repos cannot be cloned until there is an initial push)
312 * verify clone path is correct
313 * verify [[APAC mirror>>||rel="__blank"]] is updating by cloning the US mirror
315 (((
316 __Private Projects:__
318 * verify you have [[permissions/access>>||rel="__blank"]] to the repo using the above testing access command
319 * verify that you have properly followed all instructions provided to you via the email; both your .netrc and .gitconfig changes must be in place on each system where you are performing git operations.
321 __Mirror issues__:
323 * if you aren't seeing the mirror updates, please wait 15 minutes for updates and double check before using the [[CAF service desk>>||rel="__blank"]] for help.
325 (% id="HHelpfulGitReferences" %)
326 == Helpful Git References ==
328 [[Subversion to Git Migration>>||rel="__blank"]]
330 [[Support for Subversion Clients>>||rel="__blank"]]
332 [[Git cheat sheet>>||rel="__blank"]] (multi-language)
334 (% id="HGitHubResources" %)
335 == GitHub Resources ==
337 * [[Example README File>>README]]
339 * [[Suggested Code of Conduct>>CodeOfConduct]]
340 * [[Repolinter>>Repolinter]]
341 * [[DCO commit-msg hook>>CommitHook]]
342 * [[E-mail address pre-commit hook>>PreCommitHook]]
344 (% id="HHelp26SupportLinks" %)
345 = Help & Support Links =
347 * [[CAF e-mail Access>>CodeAuroraMail]]
348 * [[CAF Mirror Information>>CodeAuroraMirrors]]
349 * [[CodeAurora Project Requirements>>CodeAuroraProjectRequirements]]
350 * [[CAF@GitHub Support and Project Requirements>>]]
351 * [[Gitolite SSH Setup>>gitolite_ssh_setup]]
352 * [[FAQ>>caf_faq]]
353 )))

My Recent Modifications

Need help?

If you need help with XWiki you can contact: