How to contribute

Created by Danielle Cummings
Last updated: Oct 20, 2015 by Ross Philipson

Workflow

There are a number of ways you can contribute to OpenXT. In the future we hope to have documentation to describe how you can contribute through testing, documentation, translations etc. The first step though is getting people to contribute code.

To do this the first thing you need to do is build the existing code. This isn't particularly difficult but there is a learning curve. Start with the instructions here: How to build OpenXT

At a high level our preferred development workflow is simply: fork, change, submit a clean pull request. What follows is a description of one example of this workflow. This is not the only way to do this and if you like to do things a bit differently please do. The high level process is simply fork, change, pull request. If you have a particular git workflow that works for you we don't intend to dictate every step. If you're not sure you're doing it right or have questions, get in touch with the community and ask questions.

JIRA ticket and GitHub development life-cycle

Creating a ticket:

  • Anyone may create new tickets.  If generating bug reports, please be specific on environment (build, hardware, etc.) and document steps used to reproduce. Once a ticket is created, the status by default is "Open" and unassigned.

Ticket status:

  • Open: This ticket is likely awaiting for someone to take ownership and start working on it.  If the ticket is assigned to someone, it is expected that it is in their queue and they should begin progress at some point in the future.  Interested parties may offer to take over the ticket and begin working it.

  • In Progress: The assignee sets this to indicate that they are actively investigating this ticket and/or in development.

    • Once work is complete, pull request(s) may then be issued that indicate completion of ticket.  The ticket owner should then assign to "Review" status, signaling to other developers that the pull requests are ready for review, and may be merged if acceptable.

    • If the developer does not think the pull request is ready for merge and is for review/feedback purposes, please clearly indicate that by titling the pull request with [RFC].

  • Review: The assignee has completed development and has issued pull request(s) for review. The pull requests are open for review, and may be declined if further changes are required.

    • If changes to a pull request are required, the pull request should be updated that work has begun on a new version and the JIRA ticket should be reverted to "In Progress".  This would indicate that they are working on the next version.  Once the new version is ready, clearly document the changes made between the versions and set ticket back to "Review".

  • Done: The pull request(s) have been merged, the assignee has validated the changes were merged satisfactorily.

Re-opening a ticket:

  • If a ticket is determined to be incomplete, anyone may re-open the existing ticket.  Please update ticket with justification for doing so.  Please be specific on environment (build, hardware, etc.) and document steps used to reproduce issues. Ensure that the ticket is assigned to the original developer.

Fork

Once you've got a functional build the first thing you need to do is fork the relevant repo from the OpenXT organization. GitHub already has great docs for the using the fork and merge request features so be sure to read up on those first:

https://help.github.com/articles/fork-a-repo

https://help.github.com/articles/using-pull-requests

For a simple example we can look at some of my previous work in which I modified some of our build metadata. In this example I moved some bitbake functionality common to two image recipes into a class and added a little bit of logging to detect a weird edge case that has given me trouble in some testing. Before you make any changes though, be sure to fork the relevant git repo from the OpenXT organization (did I say that already?). So in this case our build metadata is in the xenclient-oe.git repo so I'd fork that.

Once you've got your own fork of the repo you need to go into the right place in your local build and set up a new remote to work from your fork. Let's assume that your build tree is relative to /usr/src. You'd want to go into the directory where the xenclient-oe.git repo is checked out and set up your new remote:

$ cd /usr/src/openxt/build/oe
$ git remote -v
origin  git://github.com/OpenXT/xenclient-oe.git (fetch)
origin  git://github.com/OpenXT/xenclient-oe.git (push)
$ git remote add mygit git@github.com:flihp/xenclient-oe.git
$ git remote -v
mygit   git@github.com:flihp/xenclient-oe.git (fetch)
mygit   git@github.com:flihp/xenclient-oe.git (push)
origin  git://github.com/OpenXT/xenclient-oe.git (fetch)
origin  git://github.com/OpenXT/xenclient-oe.git (push)

Knowing that the OpenXT build scripts checkout this repo at this specific path isn't something that people will know off the top of their head. This is where the learning curve for contributing to OpenXT is steepest. The best thing to do when you have questions about this sort of thing is to go into the #openxt IRC channel on freenode and ask.

Push to your Fork & make a pull request

You can make your changes and commit them just like you always do with git but before you can push you need to set up the remote to your fork as described above. We prefer to keep the central repository code history clean, so if you have extraneous local commits you should also rewrite your history to clean it up. When you push your work, be sure to name your remote:

$ git push mygit master

This is the part where you iterate and test. Please be sure to test your changes before submitting them for inclusion in the project. Once your testing is done and you're happy with the results log into git and use the pull request mechanism to get someone to review your commits.

Dos and Don'ts

Do:

  1. Build the code.
  2. Fork to your hearts content.
  3. Send us clean pull requests and discuss architecture, code and other related stuff in the discussion forums.
  4. If people have a lot of working commits in their forks of OpenXT repositories then they'll probably clean them up before submitting. Therefore please assume that changes in forked repositories may be rewritten.

Don't:

  1. Even if you have write access to the repos in the OpenXT organization please don't push there directly. For now we're trying out the GitHub pull request mechanism to see if it's "the right way" to get code review done before commits go into the "official" OpenXT repos.
  2. Circumventing the pull request and review process is discouraged.

RFC Submission

Prior to embarking on new features or large functional changes to a project, often an RFC will be submitted to get feedback on the proposed effort. This is a very standard practice and we would like to encourage its use on the OpenXT project as well. To begin with, there is the standard RFC layout that has been around for years. E.g. this IETF one for HTTP 1.1:

https://www.ietf.org/rfc/rfc2616.txt

This RFC about RFC's is also helpful:

http://tools.ietf.org/html/rfc2119

And some more RFC guidelines:

https://www.rfc-editor.org/policy.html

In general, following the IETF RFC format to a greater or lesser degree is a reasonable choice.

Best Practices

The OpenXT organization would like to make some suggestions as to what the community believes would be best practices in format and content for submitting RFC's. First though, realize that the OpenXT community welcomes all contributions to the organization. So if someone has good reason to make a submission using their own format/content/etc, they should do so. An example is a contributor that has an existing specification with many diagrams embedded in it that fully describes their system and wants to add it to their RFC (perhaps as an attachment). The downside to this is that other formats require reviewers to use other tools and it is not as easy (or even possible) to comment inline within the RFC.

The preferred format for RFC submission is plain text directly inline in a post on the mailing list (Google Group). This allows easy viewing without special tools. It also allows simple inline comments and suggestions to be posted back to the list.

The RFC should contain the following elements:

  • Title: The RFC should include a succinct single line title that indicates what the RFC is; this should also be part of the subject for the posting.
  • Date: The RFC should include the month and year for the submission.
  • Abstract Section: The RFC should provide a concise and comprehensive overview of the purpose and contents of the entire document.
  • Body Section: The RFC should have a body where the bulk of the information resides.

Some other elements an author may or may not want to include:

  • Copyrights: The RFC can include multiple copyright lines.
  • Authors: The RFC can include author's names, emails and contact information.

A few other things to keep in mind:

  • The abstract section should clearly indicate why the submission is being done, what problem the proposal is solving and why it benefits the OpenXT organization.
  • If the body section is very large, the author should consider using a TOC or some other means to organize the text. This will also make it easier to reference specific items by a number or tag.

Example:

RFC for Paravirtual Framus Driver Support

November 2014

Abstract:

This document specifies a proposal to add new PV Framus drivers
to provide virtual Framus support for guests in OpenXT. Framus
hardware has become ubiquitous on most PC hardware and providing
virtual Framus support to guests is vital to any virtualization
platform including OpenXT. The remainder of this document will
outline exactly how Framus virtualization can be achieved using
...etc...etc

Body:

Etc...etc...etc...

Code Submission

When you are ready to start contributing code, take a look at the Coding pages for tips on commenting patches, formatting, commit messages, etc.