Code Aurora GitHub Projects

Last modified by Lisa Lammens on 2018/02/22 22:27

Introduction

CAF@GitHub is intended to be used for collaborative Open Source projects hosted under The Linux Foundation Code Aurora Forum project. It is also used to facilitate contributions to other 3rd party Open Source projects that are hosted on GitHub.

Before working with Git and GitHub for the first time we recommend reviewing the online GitHub training.

The basic steps in the CAF@GitHub workflow are:

  1. Complete the relevant  project setup process
  2. Create a GitHub account and associate your Code Aurora e-mail address.
  3. Set up SSH
  4. Follow our getting started example

Creating a GitHub Account

If you already have a GitHub account and wish to associate your CAF@GitHub contributions with your account you will need to add your CAF e-mail address to your GitHub account. This help documentation from GitHub explains how to add an additional e-mail address to your account.

If you do not have a GitHub account, please see the GitHub help article to learn how to sign up for a free account. You should use your CAF e-mail address if this account is being created to collaborate through a CAF@GitHub repository.

SSH Setup

GitHub provides good help on how to set up ssh for your platform. SSH is the easiest and most secure option for controlling access for pushing code to GitHub.

Contributing

Remember all contributions should be signed off by the Developer Certificate or Origin (DCO). Agreement to this is typically indicated by use of the "Signed-off-by" tag in a commit message. For example:

Fix the bug with negative width values

Signed-off-by: Jill Developer <jill.developer@codeaurora.org>

The DCO is explained using Linux as an example on the embedded linux wiki.

Please use a commit-hook to verify the DCO sign off of commits being pushed directly into CAF repositories. This will help avoid making mistakes and negate the need for manual checking.

Getting Started Example

Once you have the repository set up in the CAF@GitHub org, you will need to clone the repository to make changes. If the repository is called "ABC", you would clone it as follows:

 git clone git@github.com:codeauroraforum/ABC.git

Ensure you set up your name and e-mail correctly (remember to use CAF e-mail). More detailed help is available here.

 git config user.email "joecitizen@codeaurora.org"
 git config user.name "Joe Citizen"

It is generally recommended to work on a branch within the git repository. You create a branch as follows (replace <branch_name> with a suitable name):

 git checkout -b <branch_name>

Subsequently when you are ready to commit the changes, you need to add the files and commit using the DCO (-s).

Then you can push them to the "remote", i.e. the GitHub server.

 git push <remote_name> <branch_name> 

Unless you have configured it differently the default <remote_name> is 'origin'. Github documentation on how to push to a remote is available here.

More GitHub tips and training can be found here.

Updating a Fork

See the following documentation from Github on how to rebase a fork to sync with the upstream.

Additional Guidelines for Collaborative CAF Projects

Collaborative projects released on CAF@GitHub (not forks or mirrors of upstream repositories) must have:

  • A LICENSE file with a well formed OSI compliant license
  • A README file, that includes instructions on how to build and test the software and a reference to the applicable license
  • A CONTRIBUTING file explaining the contribution process, including DCO sign off
  • A CODE-OF-CONDUCT
  • 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.  
  • Copyright and license headers in every source file.

Collaborative projects should have:

  • A test suite
  • Continuous Integration

Please see our Support for resources to help meet these standards.

We have a DCO Example Hook and an Commit Author Example Hook

We encourage using repolinter to enforce these rules. An example repolint configuration for this is available at Repolinter.

Additionally, the DCO pull request checker should be enabled for all incoming 3rd party contributions.

Project Administration

You will need to contact CAF Admins to perform the following actions:

  • Add a Fork into CAF@GitHub
  • Transfer a Project to CAF@GitHub
  • Add a new project to CAF@GitHub
  • Add/Remove a user from a project
  • Mirror between CAF@GitHub and the main CAF site.

You can contact CAF admins by e-mailing ITPeople AT codeaurora DOT org. If you are working on a CAF project on behalf of a company, please contact your relevant Open Source team to get instructions on how to set up projects and collaborate.

Helpful GitHub References

Subversion to Git Migration
Support for Subversion Clients
GitHub cheat sheet (multi-language)
GitHub tips and training

Tags:
Created by Craig Northway on 2017/12/09 20:54
   
This wiki is licensed under a Creative Commons 2.0 license
XWiki Enterprise 7.4.3 - Documentation