Git workflow

[mvdw]

I am a long time svn user, but never used git.

I want to add some features/bug fixes to the stm32 micropython port. Writing the C code is not that difficult (in theory...), but getting my mods pushed back into the main repository are problematic for me. Is there a a basic git workflow I should be using? I see the page at https://github.com/micropython/micropyt ... elWorkflow but not much of it makes a great deal of sense to me.

Basically a recipe for checkout-branch-dev-remerge with no jargon, for the recommended micropython dev workflow would be useful.

eg:
Get the master repository:
git clone https://github.com/micropython/micropython
(then what if I want to make mods???)
git XXX (rebase? stash?? What should i do here to make my own branch?)

Then once I've done my (atomic) changes, tested etc, I want to make my changes reflected in the master. What is the command for this?

git XXX (push/pull/clone/what??)

Bear in mind my usual workflow is:

svn co https://server/repository
(change change change fix fix test test fix test)
svn ci

[dhylands]

This is the git workflow I use:

First of all some setup:
- Get a github account
- Setup ssh on your machine, and register your ssh public key with github
- Clone the MicroPython repository:

Code: Select all

git clone https://github.com/micropython/micropython.git

- Fork the micropython repository into your own account
- Add a remote for your fork to your local repository. The commands shown are what I use. Your URL will be slightly different

Code: Select all

cd micropython  # Whatever directory you created your clone in
git remote add dhylands git@github.com:dhylands/micropython.git    # (I used the SSH URL)

My typical workflow then goes something like this:
- Edit files
- Realize I forgot to create a branch - so create one:

Code: Select all

git checkout -b my-branch-name

- Add files and commit them:

Code: Select all

git add somefile.c
git commit

I use git commit the first time I check into the branch, and git commit --amend when I checkin the second and subsequent times. This effectively squashes the commits into a single commit. If you forget to use --amend you can can always squash multiple commits together later on.

In order to sync up with the latest master, you need to commit or stash all of your changes. Then you can use

Code: Select all

git checkout master
git pul

to get the latest version of micropython. I then typically rebase my branch to the latest master that I just pulled:

Code: Select all

 git checkout my-branch-name
 git rebase master

When I'm finally ready to create a pull request (or I just want to backup my changes onto github) then I do:

Code: Select all

 git push dhylands my-branch-name

then I I visit https://github.com/micropython/micropython and my branch will show up near the top with a "Compare and pull request" button. Click that, verify that it looks like you want.

Then it's up to one of the people with commit access to actually merge your changes, or for anybody to make comments.
If you need to update something, then go back, make changes:

Code: Select all

git checkout my-branch-name
edit source files
git add source files
git commit --amend
git push -f dhylands my-branch-name

Pull requests are branch based, so you don't need to create another pull request. github doesn't send any notifications out though when you just update an existing pull request, so I normally goto the website and add a comment stating that I've updated the pull request and it's ready to look at again.

If I skimmed over something, feel free to ask for more clarification. github also has some documentation about pull-request based workflows:
https://help.github.com/articles/using-pull-requests/

[mvdw]

Perfect, Thanks Dave! FYI I am working on the DMA SD Card access, since that is the major stumbling block to my python code working properly.

So far I have it compiling. But no SD Card access yet

[stijn]

Note: while dhylands' explanation is completely correct and lays out the principle nicely, I find it easier to have my own fork as 'origin', and the offcial micropython as 'upstream' (or whatever name you want). Mainly because most of the time I am pulling/pushing from/to my own fork (especially when working on different machines), this means I can just writ push/pull commandos without having to specify the remote all the time. Doesn't change anything for local work like comitting.

init:

Code: Select all

git clone https://github.com/<yourname>/micropython.git
cd micropython
git remote add upstream https://github.com/micropython/micropython.git

to sync with upstream (after committing/stashing local stages):

Code: Select all

git checkout master
git pull upstream master
git push #push new master to your own fork as well

These last two lines are basically the only difference: you specify the remote when pulling but not when pushing, while with dhylands' way it's the other way around.