-
Notifications
You must be signed in to change notification settings - Fork 39
Contributing
Contributing to OpenXT will be a bit awkward while we're establishing our process. Currently we're transitioning from a closed to an open source model so we don't yet have a handle on all of the new tools that we're using. For now this page is a "best practices" sort of guide.
Other pages related to contributing:
[RFC Submission](RFC Submission)
[Commit Message Guidelines](Commit Message Guidelines)
We're using the available free tools as much as possible. You're reading this on GitHub so you already know that we're using GitHub to host our repositories. This wiki feature is nice as well so we're migrating / building up our documentation here. We also have a "Google Group" set up for general discussion:
https://groups.google.com/forum/#!forum/openxt
Feel free to join the group and discuss any / all aspects of the project. The use of these tools is subject to change in the future. If it turns out that (for instance) the Google Group doesn't work the way we want / need it may be that some will expend the resources to set up an "old-school" mailing list. But for now, we're sticking to the free stuff.
We're tracking bugs / issues in JIRA: https://openxt.atlassian.net
We also have an #openxt IRC channel set up on freenode. Feel free to join and ask questions there too.
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 has the following 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 is actively investigating and/or in development.
-
Review: The assignee has completed development and has issued pull request(s) in which they are confident that they are ready for merging. 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 is satisfied that the ticket is complete.
Life-cycle example:
-
Ticket is created, the status by default is "Open" and unassigned.
-
Individual taking on ticket should assign ticket to themselves.
-
When beginning work on the ticket, ticket owner should mark it "In Progress".
-
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 changes are required, the pull request should be closed and the ticket should be reverted to "In Progress". This would indicate that are working on the next version. Feel free to leave additional review feedback.
-
Once the ticket is merged, the ticket should be closed. The assignee is responsible for closing the ticket by clicking "Done" on the ticket, once they validate the changes were merged satisfactorily.
If someone determines that the merged fixes did not fully correct the problem, the ticket may then be re-opened by the reporter. The reporter should document their steps used to reproduce the issue in the ticket or provide other justification.
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.
Build the code. Fork to your hearts content. Send us clean pull requests and discuss architecture, code and other related stuff in the discussion forums.
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.
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. Circumventing the pull request and review process is discouraged.
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.
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.
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...