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.
Creating a ticket:
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.
Done: The pull request(s) have been merged, the assignee has validated the changes were merged satisfactorily.
Re-opening a ticket:
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.
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.
Do:
Don't:
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:
Some other elements an author may or may not want to include:
A few other things to keep in mind:
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... |
When you are ready to start contributing code, take a look at the Coding pages for tips on commenting patches, formatting, commit messages, etc.