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.

...

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.

Commit message guidelines

This is a set of guidelines for how to format commit messages for various types of commits to OpenXT. Because OpenXT uses the Github pull request mechanism, the standard patch submission via mailing lists guidelines don't really apply. There are mainly two types of commits that are addressed here. General commits are those where a pull request has one or more commits that will go directly into a repository. Patch commits are slightly different. It is still a direct commit to a repository (a patch queue in this case) but the committed item is actually a patch.

General Commits

For a given pull request with say a number of commits in it, each commit should have a comment block that looks like this:

Short description

Long description, multiple lines.

OXT-X, OXT-Y, etc

Singed-off-by: Jon Q. Public <jon.public@somewhere.com>

The short description should be 80 characters or less (basically 1 line). The long description could be optional if the short description says it all but that is usually not the case. The OXT ticket numbers list the JIRA tickets associated with the commit. If there are none, then this list is empty. Finally there is the standard Signed-off-by line. In addition other standard tag lines like Acked-by, Tested-by etc could be present.

Patch Commits

For patch commits the community would like the actual patch to contain a patch header message. The format of that message should be consistent with the upstream project the patch is related to. If it is not related to any upstream project or the committer is unsure, use the format for general commits. Below are links to guidelines for some of the common upstream projects:

OpenEmbedded:

http://openembedded.org/wiki/Commit_Patch_Message_Guidelines

Linux Kernel:

https://www.kernel.org/doc/Documentation/SubmittingPatches

Xen:

http://wiki.xenproject.org/wiki/Submitting_Xen_Project_Patches

Qemu:

http://wiki.qemu.org/Contribute/SubmitAPatch

Here is an example of a patch with a header message included in the OpenEmbedded project:

http://cgit.openembedded.org/meta-openembedded/diff/meta-oe/recipes-support/libyaml/files/libyaml-CVE-2014-2525.patch?h=master-next

Finally since these are actual commits to Github too, a general commit message would be needed that is outside of the committed patch itself. This commit message can either match the one in the patch or follow the general commit guidelines above and it should contain the OXT JIRA ticket numbers list.

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.

...

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 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.