Managing a forked repository
- This article is part of a series that discussing best practices of managing a UPM repository on GitHub. See part 1, part 2, and part 4.
- Feel free to check out openupm.com to discover more open-source UPM packages, and support OpenUPM at patreon.com/openupm
As the time of writing, 20% of packages published on the OpenUPM platform are forked from upstream repositories. One popular reason to fork a repository is that the original author doesn’t have time to maintain a UPM package. In this article, we’ll discuss how to maintain a forked repository efficiently.
Table of Contents
∘ Syncing with upstream repository automatically
∘ Version control
∘ Conclusions
Syncing with upstream repository automatically
Fork a repository is fun, but keep syncing changes from the upstream can be boring. Thanks to wei/Pull app, a handy GitHub application can help us keep the fork up-to-date via automated PRs.
Fork the upstream repository as usual, then install the Pull app.
I suggest below branch pattern to manage a fork,
- The local master branch as a one-to-one copy of the upstream master.
- The new upm-convert branch as our working branch to adopt to UPM package. You can set up the upm-convert branch as the default branch to avoid confusion.
Create the upm-convert branch.
# create a branch
git checkout -b upm-convert# sync with remote
git push -u origin upm-convert
Make necessary changes to add UPM support to the upm-convert branch. There’re many good tutorials around the Internet, so we will just cover the basics.
- Make sure the upstream repository has an open-source license.
- Fork the upstream repository.
- Pick a suitable package name, add package.json and asmdef files.
- Test your UPM package.
Add file .github/pull.yml as below.
- Whenever the upstream master branch is updated, the local master branch will be synced. The
hardresetmerge method will swipe any local changes to keep identical. Notice that as a free service, the Pull Github app triggers every couple of hours, but there’s an option to trigger it manually. - Whenever the local master is updated, the app will create a PR to merge to the upm-convert branch. If you don’t merge the PR, it will keep update with upstream changes until you merge it.
- Review the changes and merge them into the upm-convert branch.
- If the upm-convert branch is not a flat package, you can create the upm branch by following this article.
Version control
The version control strategy can be various depends on the upstream repository.
If the upstream doesn’t have any version control, or you have dramatically changed the repository content, you can create your versions.
If the upstream already has version control, it’s better to keep consistent with it. But how to present your changes to an existing upstream version? Two tactics:
- Use a prerelease identifier:
major.minor.patch-[prerelease-identifier].build(e.g.3.1.0-rc.1,3.1.0-preview.1or3.1.0-post.1). It works, but a version with this pattern is considered a prerelease. Thus, it won't list as a newer version in the UPM window comparing with the version without a prerelease identifier (e.g.3.0.0>3.0.0-rc.1). The workaround is that always release with a prerelease-identifier. - Use a transformed patch number:
major.minor.patchwith 2 extra digits appended to the patch number (e.g.3.1.1transforms into3.1.101,3.1.102…). See the image borrowed from the jillejr.newtonsoft.json-for-unity package below.
It works with one “glitch” when the upstream patch number is zero. If the original version is3.0.0your version will be3.0.1,3.0.2... Because3.0.001transforms into3.0.1during the npm publishing. It can be slightly confusing but won’t be conflicted.
Conclusions
This tutorial shows how to manage a forked repository. Please check out the example project: favoyang/UnityBezierSolution-UPM and the commits history.
Feel free to check out openupm.com to discover more open-source UPM packages, and support OpenUPM at patreon.com/openupm
