git-flow extension for developers

C programming, build, interpreter/VM.
Target audience: MicroPython Developers.
ihornehrutsa
Posts: 35
Joined: Sat Oct 26, 2019 8:38 pm

git-flow extension for developers

Post by ihornehrutsa » Sat Oct 10, 2020 6:03 pm

Hi everyone.
I plan to contribute code to the ESP32 MicroPython port.
Some questions:
1) Do Micropython authors use the git-flow development model?
See "git-flow cheatsheet" https://danielkummer.github.io/git-flow ... index.html
based on "A successful Git branching model" https://nvie.com/posts/a-successful-git ... ing-model/
It allows concentrate into a problem inside the separated branch (for example "github.com/micropython/micropython/feature/xxx"), not in the "github.com/micropython/micropython/master" branch and not in forked "github.com/xxx/micropython/master" repositories.
I think that git-flow allows to decrease the number of opened Pull requests and reduce merge conflicts.

2) From which branches built daily unstable firmware published on
http://micropython.org/download/esp32/
like esp32-idf3-2020mmdd-unstable-v1.13-commit.bin ?

3) Also I interested for approve "ports/esp32/machine_pwm: Add support for all PWM timers and modes. #3608" https://github.com/micropython/micropython/pull/3608
But it stopped for months. :(

To Damien George: Is it possible to create a branch 'feature\esp32_pwm' with applied PR#3608? Then I will create a Pull Request to that branch.

User avatar
jimmo
Posts: 2754
Joined: Tue Aug 08, 2017 1:57 am
Location: Sydney, Australia
Contact:

Re: git-flow extension for developers

Post by jimmo » Tue Oct 20, 2020 6:55 am

ihornehrutsa wrote:
Sat Oct 10, 2020 6:03 pm
I plan to contribute code to the ESP32 MicroPython port.
Excellent! :)
ihornehrutsa wrote:
Sat Oct 10, 2020 6:03 pm
1) Do Micropython authors use the git-flow development model?
Not exactly.

For one thing, there are never any "merge" commits in MicroPython. All commits from PRs are rebased onto the "master" branch.

I don't know much about "git-flow" specifically but it does sound a lot like what I've done when working with git (and GitHub) in a small repo where everyone on the team is a maintainer. i.e. exactly what you'd do for a private GitHub repo within a company working on a product.

This isn't at all how something like MicroPython works.
ihornehrutsa wrote:
Sat Oct 10, 2020 6:03 pm
I think that git-flow allows to decrease the number of opened Pull requests and reduce merge conflicts.
I don't know enough about git-flow to understand this. Each PR is (ideally) a separate contribution or feature. Why does git-flow help reduce the number of pull requests?

The model that MicroPython uses is really simple (and as I understand it, quite common to other open source projects on GitHub):

- Fork micropython/micropython to you/micropython
- Clone you/micropython as "origin" and micropython/micropython as "upstream"
- Start a new feature/fix by fetching upstream, then branching off upstream/master
- Push your branch to origin
- Raise a PR for your-branch from you/micropython against micropython/micropython
- Address review comments (either add new commits or modify existing commits)
- Re-push to origin

Periodically you might need to rebase your branch on upstream/master, but that's usually pretty straightforward. (And the only situations where it isn't would also be an issue for merging).
ihornehrutsa wrote:
Sat Oct 10, 2020 6:03 pm
2) From which branches built daily unstable firmware published on
"master".

Almost everything in micropython/micropython happens in master. All development happens in private forks.
ihornehrutsa wrote:
Sat Oct 10, 2020 6:03 pm
3) Also I interested for approve "ports/esp32/machine_pwm: Add support for all PWM timers and modes. #3608" https://github.com/micropython/micropython/pull/3608
But it stopped for months.
Sadly it looks like the original author has abandoned it. If you're interested in continuing it then that would be excellent!
ihornehrutsa wrote:
Sat Oct 10, 2020 6:03 pm
To Damien George: Is it possible to create a branch 'feature\esp32_pwm' with applied PR#3608? Then I will create a Pull Request to that branch.
That's now how the project works unfortunately (or most open source projects as far as I understand). You can just create your own branch containing the same commits as 3608 (either add it as a remote or use the refs/pulls feature, then rebase on master), and then send that as a PR indicating that it is based on the work from 3608.

stijn
Posts: 735
Joined: Thu Apr 24, 2014 9:13 am

Re: git-flow extension for developers

Post by stijn » Tue Oct 20, 2020 11:46 am

To Damien George: Is it possible to create a branch 'feature\esp32_pwm' with applied PR#3608? Then I will create a Pull Request to that branch.
To add to what Jimmo says: practically the easiest to get that code (I think) is to create that branch yourself by pulling from the Github PR. Setup a git alias so it looks like

Code: Select all

alias.fetchpr !sh -c 'git fetch upstream pull/'$1'/head:pr/'$1''
then you run 'git fetchpr 3608' and you get a branch pr/3608 with it's code.


Wrt git-flow: I've used it in a team for like 5 years on multiple repositories which according to it's explanation are the sort of code git-flow is ideal for. In my opinion it's too much overhead in general, and especially the widespread use of merging pretty much everything results in a lot of cognitive overhead (truns git log graph view into a mess) and makes it much harder than it should be to track file/line changes back to their exact origin. Another example: the idea of having separate master/develop branches sounds nice in theory, in practice it merely results in needing extra git commands to get the 2 in sync ('hey we need a new release' -> 'wait first need to merge develop insto master'). Not sure how it results in less merge conflicts: merge conflicts originate from having different commits affecting the same piece of code. No matter what you do, that's bound to happen. Things like hotfixes are actually a good candidate for merge conflicts because they are not based off master but of an other version of the code. Likewise for decreasing number of PRs: that's orthogonal to whatever the underlying VCS even is, so I don't understand the link. I also had the impression for junior developers git flow tends to be an excuse to not learn what git actually does, i.e. they learn clicking 'start feature' in SourceTree or so but once things end up in a mess they're lost because they don't know the underlying git commands. tldr; it could work, but I'd love to see a practical example where the overhead and time spent on that is worth it, vs e.g. a simpler model like one master branch with tags for releases and all work getting done in feature branches which are rebased onto master.

ihornehrutsa
Posts: 35
Joined: Sat Oct 26, 2019 8:38 pm

Re: git-flow extension for developers

Post by ihornehrutsa » Wed Oct 21, 2020 7:04 pm

Thanks, jimmo.
I understood and accept the 'simple' MicroPython developer flow cycle.
It ideal for 'One developer' -> 'One pull request' -> 'One acceptor into master thread'.
How do several developers work under one task/issue?
He must make its own Pull Request to the forked repository or to the upstream https://github.com/micropython/micropython ?

Thanks, stijn for that

Code: Select all

alias.fetchpr !sh -c 'git fetch upstream pull/'$1'/head:pr/'$1''
I wrote into my Ubuntu '.bashrc'

Code: Select all

fetchpr() {
  git fetch upstream pull/"$1"/head:pr/"$1"
}  

User avatar
jimmo
Posts: 2754
Joined: Tue Aug 08, 2017 1:57 am
Location: Sydney, Australia
Contact:

Re: git-flow extension for developers

Post by jimmo » Wed Oct 21, 2020 10:50 pm

ihornehrutsa wrote:
Wed Oct 21, 2020 7:04 pm
It ideal for 'One developer' -> 'One pull request' -> 'One acceptor into master thread'.
How do several developers work under one task/issue?
He must make its own Pull Request to the forked repository or to the upstream https://github.com/micropython/micropython ?
If it's one task/issue then it's still one pull request.

A pull request is from some branch somewhere else on github, so you can use whatever workflow you like to work collaboratively on that branch. i.e. you can invite other people to collaborate with github.com/<you>/micropython and work together on the feature branch that you've made the PR from.
ihornehrutsa wrote:
Wed Oct 21, 2020 7:04 pm
I wrote into my Ubuntu '.bashrc'
I think he was suggesting to put this into your gitconfig. i.e. so you can write "git fetchpr ...".

stijn
Posts: 735
Joined: Thu Apr 24, 2014 9:13 am

Re: git-flow extension for developers

Post by stijn » Thu Oct 22, 2020 7:11 am

It ideal for 'One developer' -> 'One pull request' -> 'One acceptor into master thread'.
Apart from what Jimmo says note that it's also possible to have multiple developers ('acceptors') which are allowed to push to the master branch and/or do other administrative tasks.
I think he was suggesting to put this into your gitconfig. i.e. so you can write "git fetchpr ...".
Yes, sorry if that wasn't clear. Also has the advantage it can be used anywhere where you an use git, also in GUI tools etc, which isn't possible if it's a bash function.

ihornehrutsa
Posts: 35
Joined: Sat Oct 26, 2019 8:38 pm

Re: git-flow extension for developers

Post by ihornehrutsa » Thu Oct 22, 2020 5:55 pm

Thanks, jimmo
Thanks, stijn

My 'micropython\.git\config' has a structure too different from the

Code: Select all

alias.fetchpr !sh -c 'git fetch upstream pull/'$1'/head:pr/'$1'
micropython\.gt\config:

Code: Select all

[core]
	repositoryformatversion = 0
	filemode = false
	bare = false
	logallrefupdates = true
	symlinks = false
	ignorecase = true
[remote "origin"]
	url = https://github.com/IhorNehrutsa/micropython.git
	fetch = +refs/heads/*:refs/remotes/origin/*
[branch "master"]
	remote = origin
	merge = refs/heads/master
[remote "upstream"]
	url = https://github.com/micropython/micropython.git
	fetch = +refs/heads/*:refs/remotes/upstream/*
I am not sure.

stijn
Posts: 735
Joined: Thu Apr 24, 2014 9:13 am

Re: git-flow extension for developers

Post by stijn » Thu Oct 22, 2020 7:26 pm

See e.g. https://githowto.com/aliases. use a command as specified there, or modify the [alias] section in your global .gitconfig file (in your home directory)

ihornehrutsa
Posts: 35
Joined: Sat Oct 26, 2019 8:38 pm

Re: git-flow extension for developers

Post by ihornehrutsa » Thu Oct 22, 2020 8:21 pm

Thanks

Add to micropithon/.git/config

Code: Select all

[alias]
  fetchpr = "!f() { git fetch upstream pull/${1}/head:pr/${1}; }; f"  
and then possible command with pull request number as a parameter
git fetchpr 3608

ihornehrutsa
Posts: 35
Joined: Sat Oct 26, 2019 8:38 pm

Re: git-flow extension for developers

Post by ihornehrutsa » Fri Nov 27, 2020 7:21 am

I want to continue here.
I want to consider the real case of the cooperative development of a feature.

There is PR esp32/machine_pwm: handle multiple timers. #6276
I can fetchpr 6276 (as described upper) and I do it and make some bugfix.
I can't create PR to the forked repository branch of #6276 (https://github.com/p1ng0o/micropython/t ... lti_timers)
because GitHub reports me: "You've already forked micropython". Well, I know.
So, then I make PR esp32/machine_pwm.c: Handle multiple timers: Bugfix PWM.deinit() critical error and fix pwm_print() #6654.
But in this case, my PR is cumulative and doesn't show the author and commits of PR #6276. And it is difficult to understand which is my bugfix.

Am I do right?
Is there a better way?

I think it is better to have a branch for the new feature, for example
github.com/micropython/micropython/tree/feature/esp32_pwm_handle_multiple_timers
and push PR to it( not to the master).

Is it possible to make PR to non exist branch in the upstream repo?
Or is it possible to make PR to create a new branch in non-writable for me upstream repo?

Post Reply