Blogi 11.2.2019

Best Practices for forking a git repository and continuing development

Kiva kun löysit tämän artikkelin! Se sisältää varmasti hyvää tietoa, mutta pidäthän mielessä, että se on kirjoitettu 5 vuotta sitten.

Sometimes there’s a need to fork a git repository and continue development with your own additions. It’s recommended to make a pull request to upstream so that everyone could benefit from your changes but in some situations, it’s not possible or feasible. When continuing development in a forked repo there are some questions which come to mind when starting. So here are some common questions and answers that I found useful when we forked a repository in Github and continued to develop it with our specific changes.

Repository name: new or fork?

If you’re releasing your own package (to e.g. npm or mvn) from the forked repository with your additions then it’s logical to also rename the repository to that package name.
If it’s an npm package and you’re using scoped packages then you could also keep the original repository name.

Keeping master and continuing developing on a branch?

Using master is the sane thing to do. You can always sync your fork with an upstream repository. See: syncing a fork.
Generally, you want to keep your local master branch as a close mirror of the upstream master and execute any work in feature branches (that might become pull requests later).

How you should do versioning?

Suppose that the original repository (origin) is still in active development and does new releases. How should you do versioning in your forked repository as you probably want to bring the changes done in the origin to your fork? And still maintain semantic versioning.
In short, semver doesn’t support prepending or appending strings to version. So adding your tag to the version number from the origin which your version is following breaks the versioning. So, you can’t use something like ”1.0.0@your-org.0.1” or ”1.0.0-your-org.1”. This has been discussed i.a. semver #287. The suggestion was to use a build meta tag to encode the other version as shown in semver spec item-10. But the downside is that ”Build metadata SHOULD be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence.”
If you want to keep relation the original package version and follow semver then your options are short. The only option is to use build meta tag: e.g. ”1.0.0+your-org.1”.
It seems that when following semantic versioning your only option is to differ from origin version and continue as you go.
If you don’t need to or want to follow semver you can track upstream version and mark your changes using similar markings as semverpre-releases: e.g. ”1.0.0-your-org.1”.

npm package: scoped or unscoped?

Using scoped packages is a good way to signal official packages for organizations. Example of using scoped packages can be seen from Storybook.
It’s more of a preference and naming convention of your packages. If you’re using something like your-org-awesome-times-ahead-package and your-org-patch-the-world-package then using scoped packages seems redundant.

Who should be the author?

At least add yourself to contributors in package.json.

Forking only for patching an npm library?

Don’t fork, use patch-package which lets app authors instantly make and keep fixes to npm dependencies. Patches created by patch-package are automatically and gracefully applied when you use npm(>=5) or yarn. Now you don’t need to wait around for pull requests to be merged and published. No more forking repos just to fix that one tiny thing preventing your app from working.

 
If you have any other questions, then post them in the comments below.

English

Marko Wallin

Marko works as a full stack software engineer and creates better world through digitalization. He writes technology and software development related blog and developes open source applications e.g. for mobile phones. He also likes mountain biking.

Takaisin ylös