deviationTx is open source firmware for the Walkera Devo line of transmitters. Since it's open source, it's possible for end users to get the source and improve it to better meet there needs. While this is an incredible feature all by itself, it gets even better. You can contribute those improvements back to the project so they become part of the standard builds. This means you don't have to keep adding them if you want new features, and other users can benefit from those changes.
This tutorial provides instructions for contributing your changes back to the project. It is more than just a simple HOWTO recipe, as I try and explain the what's and why's as well as the how's. I hope that helps you figure out how to fix things yourself if things go wrong.
I purposely explain things I suspect you already know, in order to avoid leaving out things I was mistaken about. So expect to get a bit of the obvious explained, and please let me know if I miss something.
The steps are:
Use bitbucket to create a fork of the deviationTx source repository.
Copy the appropriate hg clone command from your repositories page on Bitbucket, and run it locally.
Copy in your changes or edit the code however you normally do it.
Use `hg ci` to commit your changes.
Use `hg push` to push your changes to your repository on BitBucket.
Issue a pull request from your repositories page on Bitbucket.
All but the first two steps and the last step are local mercurial operations. You can skip those if you are already familiar with mercurial.
Now to look at the steps in detail.
The deviationTx project source is hosted on Bitbucket. So your first step is sign up for a Bitbucket account. Get a personal account, as they are free. Getting a username that's as much like your deviationTx username is recommended.
The source on Bitbucket is stored in a version control system. The source for each different project is stored in a different repository. You'll need to make your own copy of the deviationTx repository in order to submit changes back to it. Such a copy is called a clone, and the act of creating it is cloning.
Now comes your first choice. You can clone the official source. At the moment, PhracturedBlue is taking a sabbatical, so no changes are being included, no new builds are being made, and so on. A team has been created so that other developers can cooperate and get all of their contributions in one version. If you want to work with that team, you can instead clone the team repository. Moving contributions from one to the other isn't hard, and will be explained at the end.
Once you've decided what repository to clone, open that page in your browser. At this time, you hover over the three dots below the Bitbucket logo in the upper left, and then select the Fork action.
At this point, you can just hit the Fork repository button, and you have a clone on Bitbucket.
If you've already got a clone of it on Bitbucket, you might want to change the name, or add your own description. If all you're going to do is contribute back to deviationTx, turn off Issue tracking and Wiki, as you won't need those features. Since the code is licensed under the GPL, don't turn on This is a private repository unless you really know what you're doing. For that matter, the rest of the options should be left alone unless you know what you're doing. But those are all optional things.
The version control system that deviationTx is stored in is mercurial . This is also called "hg" (the chemical symbol for mercury), because that's the name of the command it installs.
You'll need to install a copy of mercurial on the system you build deviationTx on. If you're using Linux or Unix other than OSX, it should be in the package system. If you're using Windows, you can install it from the download link on the mercurial home page. I'm not sure you can build deviationTx on OSX, but it should be in the third party package systems, or you can install it from the downloads link on the homepage.
There are lots (and lots and lots) of options for mercurial. You don't need most of them. You should configure your username, though. To do that, create the file %USERPROFILE%\mercurial.inion Windows, and $HOME/.hgrc on everywhere else. It should have the two lines in it:
[ui]
username = Firstname Lastname <email@example.net>
Change Firstname Lastname to be whatever name you want to use. Also set email@example.net to your email address.
Now you can create a local clone of your repository. To do that, go to the page for your repository and the three dots on the left again, only this time select Clone. It will pop up a rectangle with some text pre-selected. Use your window managers copy facility to make a copy of that. Now get a command line window open, go to the directory you want the source to be stored in, paste that text and hit enter.
This will run an hg clone command to create a local copy of the repository. Before hitting enter, you can edit the command. The most important one is to set the name of the directory that is going to be created. The default will be the same as the name of the repository, but you can type a different name as a second argument to the clone command.
Version control systems are much to complex to cover in any detail, and mercurial is a relatively complicated one. While I'll cover enough to get you through the process here, that's about all I'll cover. If you run into problems, hg help will list the available commands, and hg help command will provide help for command. The mercurial web site has a page listing a number of beginners guides and cheat sheets if you want to learn more.
You can now edit the files in the created directory just like you would the raw sources. That includes copying files from an existing version into it. Follow the existing instructions to build the software and do whatever testing you want. When you're happy, you're going to prepare to check it in.
The first command you want to try is hg status. It will list all files that are different from what was checked in or out most recently, which when you start is the most recent code in the repository you cloned. The type of modification is indicated by the first character of the line, the important ones being: M for modified, A for added, ? for files that it doesn't know about.
To check on the details of a files changes, you can us hg diff. By default, it lists the differences to all modified files. You can limit it to specific files by listing them as arguments.
If you decide you've screwed things up beyond repair, you can use hg revert --all to go back to the code you last checked in or out. Or instead of --all, provide file names to revert only those files.
Once you've got the right sources in the directory, make sure mercurial knows about all the files you've added that need to be checked in. Use hg status to check that they are listed with a A. If they are listed with a ?, use hg add. By default it will add all files marked with a question mark. You can provide file names on the command line to only add those files
Once you have the right set of files modified and added, you can do hg ci to commit your changes to your repository. This cannot be undone except by deleting the repository and creating another local clone, so be sure you're ready to commit it before you do. But before you do commit, you have another choice to make.
If you're going to be making more than one contribution, you will want to create pull requests for each of them. That requires that you either have a new repository - both locally and on Bitbucket - for each change, or that you put each change in a different branch. The latter requires that you create a branch before you commit.
To create a branch, just run the hg branch command with the new branch name. For instance: hg branch my_new_feature. That's all it takes - your next commit will create a branch.
When you commit your changes with ci, you will have to provide a description of the changes. If it's short, you can use the -m option like so:
hg ci -m "Making deviationTx better!"
though you'll hopefully provide a better description than that. If you want a longer description, or feel an explanation is needed, leave off the -m option and description string, and an editor will be opened so you can provide a longer message. By convention, the first line is a short description, then a blank line and the longer text.
Don't forget that more information about all the commands can be had at any time with hg help!
After that finishes, you will have committed your changes to your local repository!
This is really easy. Just issue the command hg push!
If you chose to work in a branch earlier, you'll want to use the --new-branch option: hg push --new-branch. Don't worry - if you forget it, mercurial will abort the push and tell you what to do.
The final step is to create the pull request. Once again, go to your repository page on Bitbucket and use the three-dot menu. This time, you want to select Create pull request. It tries to choose smart defaults, but you should double check them. The left-hand repository is yours, and the pull-down box in it should say default or the name of your branch if you are using branches. The right hand side is the destination. It should be the repository you cloned your repository from - either deviationtx/deviation or PhractureBlue/deviation. The branch should be default.
Change the title if it's not accurate, and then add a longer description. You can also take this chance to look through the diffs one last time. When you're happy with the results, click Create pull request.
Well, you've created the pull request, but you're not done. You may well get feedback from the authors and other uses, suggesting changes. If you make those and then push them to your repository, the pull request will be updated appropriately. This is why you want to use multiple repositories or branches if you're going to make more than one contribution.
While the above covers the basics, there's a few advanced things that might help without getting down and dirty with mercurial.
If you're keeping your contributions in multiple repositories, you can pull changes between them with hg pull repository, where repository is either the directory holding the other repository, or the URL for he repository on Bitbucket.
If you're using the same repositories often, you can edit the file .hg/hgrc in the top-level directory of your repository to add aliases for them. The section [paths] will have a single alias in it for default, which is used if you don't specify a repository. You can add others if you need them. For instance, I have:
team = ssh://hg@bitbucket.org/deviationTx/devation
pbr = ssh://hg@bitbucket.org/PhracturedBlue/deviation
which allows me to pull changes from those two repositories directly into my working copy, without having to go through the clone on Bitbucket. When I push back to my clone, the changes I pulled in will be pushed back as well.
As you will notice from the above, you can pull from any repository. In the same way, other people can also pull from yours - at least if you left your Bitbucket repository public. All they need is the URL of the repository.
You can give them that, using the default path from the hg paths command in your local repository, or via the Clone feature of the repository on Bitbucket. Or they can find it by finding your Bitbucket user name and the list of repositories you have there, or get the link from a pull request you've created.
They can also get a branch name the same ways. Finally, you can let them push changes to your repository by giving them write permission to it.
On the repository page, start with the Gear icon in the bottom of the left column. Click Access management near the top of the newly created column beneath the Settings heading. The main part of the page will now have a Users section. Each user other than the creator - probably you - will have three buttons for Read, Write and Admin access. Just select the right button. If the user you want to let write isn't listed, use the text entry bar near the top to add them. The pull-down menu can be used to add them with write permission.
If you're keeping your contributions in separate branches in one repository, then your changes are already in place.
Usually, each new branch should start from the tip of the default branch for that repository. To change back to it, do hg co default. Then make your changes and create a new branch just like you did the first time.
You can move back to your other branches with with hg co my_branch.
And now, as promised, here's how to create a pull request on the other repository if you were working with one.
Bitbucket will only let you create pull requests to a repository from a fork of that repository. So you'll have to fork the repository you haven't been working in on Bitbucket, as described above.
Create a local copy of that new clone as described above. Now, pull the changes for the pull request from a repository that already has them - either your local working copy of it, or the Bitbucket repository that you pushed it to: hg pull repository. If you were working on a branch, you can specify that you only want that branch with hg pull -b my_branch repository.
Now that you have the changes in a local clone, push them back to the Bitbucket clone and create a pull request there, just as you did with the original.
Note that if the tips of the two repositories are different, this can create some issues for you. If there are commits to default after the tip of your current repository but before the branch, the pull will bring in all of those as well, even with the -b option. Those will show up in the pull request.
One way to deal with this is to start from what is the tip of the repository that is furthest behind, no matter which it is. You'll then have to merge the changes when you pull on the other one, which topic is beyond the scope of this already too lengthy tutorial.
One thing you can do to make this easier is to create a bookmark in your local repository that points to the tip of the other one. Then you can check out that bookmark to start from it. The command is hg bookmark -i name to create the bookmark name. The -i makes it inactive, so it won't update automatically.