How to contribute using GIT
The wxPython code is stored in a GitHub repository and the preferred way of providing changes is via PR's (Pull Requests), the following page will provide some pointers on how to work with git and Github.
The first thing you should do is create a free Github account and fork the wxWidgets/Phoenix repository (see top right of screen), see also Fork a repo. Then to get this code to your local PC you need to clone the fork you did, see also Git basics.
If you are planning on building the Phoenix binaries then you will also need the wxWidgets source. The correct version of the wxWidgets source is available as a git submodule in the Phoenix source tree, so if you run the following commands git will fetch a copy of the wxWidgets source for you:
1.
cd yourphoenixclonedir
2.
git submodule init
3.
git submodule update
You should repeat #3 once in a while (or perhaps everytime you pull down new changes) to make sure that you have the linked revision of wxWidgets in your workspace.
Create a pull request
A PR can be a simple one line change or a new widget or anything in between this. A pull request can be commented on and often the comment will mean changes to a PR before it will be merged, therefore it is strongly suggested to create a branch in your clone of the repo for each PR.
Following are the steps using the git cli and assumes you have ssh setup. I personally do this all in the UI client I use, until today that was Tortoise for GIT but Robin just mentioned SourceTree, which I have to say is much nicer and handles both git and hg repositories.
1.
cd yourphoenixclonedir
2.
git checkout master
switches to the master branch, if you just cloned then you already have the master branch checked out
3.
git status
allows you to check on which branch you are
4.
git checkout -b yourbranchname
create a new branch called 'yourbranchname' and switch to it. Do not skip this step. Submitting your master branch as a PR can sometimes have problems if master is updated before your PR is reviewed.
5.
make changes and do
git commit -a -m 'add your first change'do this frequently, use a better commit message than the one shown
6.
git push --set-upstream origin yourbranchname
this copies your commits from the local repository to your default remote repository, which is likely your fork on GitHub. --set-upstream will create your branch on your remote repository. So when you push the next time with the same branch can do just git push.
7.
create the PR on your github account from 'yourgitaccount/Phoenix:yourbranchname' (the "head fork") to 'wxWidgets/Phoenix:master' (the "base fork")
8.
watch for comments and suggestions about your PR at GitHub
9.
make changes as needed from the suggestions and commit those changes
10.
git push
this copies the new changes up to GitHub and the PR will be updated automatically
Resync your fork with Robin's master
After Robin has merged your change or done other changes to the master branch you need to get this into your fork.
Your fork is normally referred to as 'origin' and the wxWidgets repository is normally referred to as 'upstream' although you can use a different name for the remote repository if you wish.
You need to add the wxWidgets repo as a new remote (called upstream) in order to pull changes made by others into your repositories.
For HTTPS
git remote add upstream https://github.com/wxWidgets/Phoenix.git
or SSH
git remote add upstream git@github.com:wxWidgets/Phoenix.git
Get the changes from upstream and push them to your fork.
1.
git fetch upstream
fetches commits from the remote repository called "upstream"
2.
git checkout master
to ensure you are currently on the master branch in your local repository
3.
git rebase upstream/master
merges those changes into your master branch, rebasing any other changes you may have made in your local branch so they appear after the upstream changes. If you haven't made any other local changes then you can use the git merge command
4.
git push
copies those changes to your "origin" remote, which is your GitHub fork
A few links to tutorials and other useful help to get going with git.
Git immersion tutorial -- This looks pretty comprehensive, just replace 'Ruby' with 'Python':)
Fork a repo -- This is what gave Robin the "Ah ha!" moment when trying to grok github.
Tips
Here are a few tips that may help make using git to make contributions to Phoenix a little less confusing while you are still getting the hang of it.
Use a branch for all your changes. Always commit your changes to a branch that is not master, so your stuff doesn't get tangled up with changes coming from upstream or other repositories. This also makes it easier to push them to GitHub for PRs and it makes it easier to wipe them out if you decide it was a bad idea.
- Use separate braches for each logical grouping of changes (like each new feature or fix.)
- Never merge your local branches to the master branch. Always wait for your PRs to be merged and come back to you from upstream.
- If new changes on the master branch come from upstream while you are still working on a set of changes, and you would like to be able to work on your changes with those upstream commits in place, you can simply merge master into your branch. This also works okay if your branch has already been made into a PR.
- If you have more than one branch (besides master) that you would like to test all together, you can make a new branch and merge all the ones you want to test into that new one. If you need to make a change, switch back to the appropriate branch, make the change, commit it, and then merge that branch back into your combined testing branch again.
Graphical tools for GIT
Until today I used Tortoise for GIT and TortoiseHG, but had to check out Robin's favoured and find SourceTree very nice and it does handle both Github and Bitbucket repo's in one UI - neat:).
On Windows
SourceTree -- What Robin uses when he isn't using Git from the CLI.
Tortoise for GIT - a graphical UI
On MAC
SourceTree -- What Robin uses when he isn't using Git from the CLI.
On Linux
"$@#!@! There's no SourceTree for Linux!" -- Robin
SmartGitHG -- It's not as smooth as SourceTree, but it is what Robin uses when he just can't figure out the CLI. Ironically, it's a NOT FREE tool that he only uses on a FREE operating system.