Tips for OpenSource Project – Git

Recently I’m working on a opensource project: it-chain/engine. I’ve participate in this project as collaborator early in the year. For about 6 month, there’re lots of hard situation to work with other developers. And also learned about how can I work with others not making awkward situation. In addition I want to share the tips to work on opensource project and how to use git, not basic tutorial but more about practices which fit into opensource project.

Work on Smaller Feature

I think this is coincide with the principle of Seperation of Concerns(SoC) Principle in software design. And this is what I utmost want to emphasize in this post. Let’s assume that you are working on food delivery service project with others. And one developer on your team issued on github that “Now I’m going to fix whole delivery system” and let’s assume that these delivery system code affects on all other sub-servcies code, like UserManagement, StockManagement. Then whenever other developers are trying to fix those sub-services, the codes will broken because the developer who works on whole delivery system will mass up whole of your codes. And I think this is one of most irritating situation. Works on smaller feature first which do not affact on others parts, then integrate with others.

Issue on github which feature I’m going to working on

Two different developers may work on same part. And at the point of pull request, the other developer who is not pull requested may panic. So this is basic but important manner to working with other in opensource project. Issue what’s I’m going to working on and tag the other developers to notify.

But code should be large enough to express functional unit

For example, someone pull requested with this single struct

// command.go
type ConfirmBlock struct {
    midgard.CommandModel
    Seal []byte
    Body []byte
}

We don’t know what is this command struct is. And where this struct are going to used. It might be better to pull request with ConfirmBlockHandler function which actually use this struct. And other can see that where this struct are going to used in the view of whole system.

Tips on Using Git

git pull -r

Usually in personal project we just pull the code. But just pull the code actually dirties your git tree if that project grow.

And there’s another advantage by using -r option. For easily rebase, pull request should have least number of commit. This convention helps each pull request have 1 commit and this also helps each pull request have smaller feature which helps other feedback your codes and also each team member can work well by not interfered with the codes that pull requested.

git commit --amend

Our team makes conventions one of which is not to make unnecessary commit and this can be the cause of reject of pull request.
To remove unnecessary commits, git commit --amend is the way. Let’s assume that you made a commit with message “add command handler”, then you find out that you forgot to add some pieces of codes, of course by mistake. But this fixes are too small to make another commit. Then you can use --amend options. You just need to type git commit --amend then the codes that you commited and the codes that you fixes are now in one commit with message “add command handler”.

git reset --soft HEAD~<NUM>

You got a feedback from pull request that you may need to combine two commits into one that you pull requested. Because other can think the second commit is unnecessary. Then you can use git reset in the local.

commit 86dd8e01a62eb3cdb395d1d0cfcd9f0911c2c381
    Unnecessary commit
commit 1ba16109049b50d877941d5385653692e7d5ded4 
    Some commit

Let’s this is the commits you made. In this situation, you need to combine Unnecessary commit into Some commit. Then you can use git reset --soft HEAD~1, with this you reset the recent one commit and those codes you made in Unnecessary commit are unstaged. Your team feedbacks you combine two commits so now you git add . and git commit --amend. Then your commits looks like this.

commit 1ba16109049b50d877941d5385653692e7d5ded4 
    Some commit