When you’re ready to take the plunge, one of the most helpful ways to contribute to the Xcore open source projects is to actually submit source code. Here’s a step-by-step listing of the things you need to do to make this a successful experience.
Learn at least something about XMOS technology, XC and the Xcore open source projects - there are some pointers in About XMOS Technology. Guidelines and examples of each class of open source repository can also be found in Classes of Repositories.
The Xcore open source project uses git for source code control. The git homepage has installation instructions. If you’re on OS X, use the Git for OS X installer. If you’re unfamiliar with git, there are a variety of resources on the net that will help you learn more:
Unlike many open source projects, the Xcore open source project consist of many repositories of multiple types. We use the Fork-And-Pull model - once you have found one that you are interested in contributing to, you need to create a fork.
Now get busy and add your code to the project (or edit the existing code). You’re on your fork now, so you can write whatever you want. But if you’re planning to submit your change back for inclusion in the Xcore open source projects, keep a few things in mind:
Each repository can be expected to have its own conventions, at least initially. Please be consistent with the conventions already established in any given project. In time, the community may develop more general and more widely applicable guidelines.
First - you need to have filled out and clicked through the contributor license agreement. This protects the community from bogus contributions and ensures that code is safe and easy for everyone to reuse. If you’ve already done this and your latest contribution conforms to the requirements, you can skip this step.
Use (or at least link to) the licenses - there is one for hardware and one for software. Don’t forget to change the copyright to your name or organisation.
For example, if you don’t want to copy the license into the top of your source code, here’s a lightweight alternative:
// Copyright (c) 2011, <insert copyright holder here>, All rights reserved
// This software is freely distributable under a derivative of the
// University of Illinois/NCSA Open Source License posted in
// LICENSE.txt and at <http://github.xcore.com/>
In this case you should also place the appropriate license in a LICENSE.txt file at the root of your repository.
When you’re happy with the code on your computer, you need to do a pull request. This (politely!) asks the maintainer to pull your changes in your fork, into the origin repository.
It’s entirely possible that the feedback you get will suggest changes. Don’t get discouraged: the whole point of contributing to an active open source project is to tap into community knowledge. If people are encouraging you to tweak your code, then it’s worth making the tweaks and resubmitting.