-
Notifications
You must be signed in to change notification settings - Fork 39
Contributing
DO NOT EDIT: This page has been migrated to Confluence: https://openxt.atlassian.net/wiki/display/OD/Getting+Started https://openxt.atlassian.net/wiki/display/OD/How+to+contribute
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:
[Commit Message Guidelines](Commit Message Guidelines)
[RFC Submission](RFC Submission)
[Code Formatting](Code Formatting)
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.
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.
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.