!=unity package mirror

All Unity Packages on GitHub

This project mirrors all packages available in the Unity Package Manager, across all versions. This allows for easier comparison of versions, checking actual changelogs, and forking to do customisations while keeping a relatively safe upgrade path.

What does it do?

The Needle Mirror organization contains all available Unity packages, with all their versions. This allows for a couple of very nice things:

1. ⚖️ Compare package versions right on GitHub, without having to download first and then see whether you actually need the changes.
   Example

2. 🥇 Easily see the order in which packages are published, including branching (ever wondered why 3.0.1 and 4.1.2 work while 3.1.4 is broken in your project?)
   Example

3. 📇 Browse changelogs written by the devs. While the technical writers do a great job, the dev changelog is usually more fine-grained and, at least to us, more helpful.
   Example

4. 🗡️ Easy forking. You still can follow updates relatively easy by rebasing to a newer version occasionally.
   Try it now for XR Interaction Toolkit

5. 📜 Release overview. The GitHub releases page makes it easy to skim through a lot of package versions and see what happened when.
   Example

6. 🔍 Search across all package code with ease, using GitHub's tools.
   Example

Why though?!

UPM (Unity Package Manager) is great. It solves a lot of pain points of working with Unity — and, while at it, introduces some new ones! Namely, since it's introduction, a common response to bugs and issues in Unity packages is "well, the source code is in your hands, go fix it yourself".

"Helpfully", package manager allows to embed a package for development, essentially cluttering your entire project / repository with all the files that were so tidily packaged away before.

Also, once you start going that "customization" route, you lose exactly what UPM is great for — updating packages to newer versions with fixed bugs.

For our own projects, we tried to minimize the impact of that in the following way:

1. Whenever changes to a package become necessary, create a new submodule
2. Put the latest version of that package into it as "base"
3. Do your modifications on top, in a branch
4. When a new version becomes available in UPM, go to the branch with the last version, delete everything and put the new version from UPM there
5. Rebase your custom changes onto the new version.

This seems to be the easiest and most comfortable way with the least headache to freely modify Unity-provided packages while still being able to upgrade*. *: rebase can be easy or hard, depending on how many changes Unity did in the meantime.

(Note that this is easier for some packages where Unity freely provides the source, such as Graphics, Input System and some others - and some of them even accept PRs!)

Turns out we did the above process a couple of times too often over the last months.
So, we decided to automate it; and make it available on GitHub for everyone.

Pain Points with Unity's approach to package releases

No easy way to compare code between versions. While the Unity Engine C# Reference Code is fully available on GitHub the same is not true for most packages.

No proper changelogs. While all project changelogs say they "follow semantic versioning" the reality is that QA does not seem to be checking this and some changelogs are better than others, while unfortunately some don't make sense at all.

• ❌❌❌
• ❌❌
• XR Interaction Toolkit ❌

Here are some notable exceptions:

• Input System ⭐⭐⭐ (this changelog is a work of art)
• Universal Rendering Pipeline ⭐⭐
• Cinemachine ⭐

Note that the first two are public repos — turns out having your Changelog user-facing and accessible with one click improves internal quality a lot! Who'd have thought!

This section is for you, dear Unity QA people

While building this, we stumbled upon a couple of issues with package structure, especially around changelog consistency.
To clarify: we're putting this here to hopefully improve quality in the future, not to shame anyone. Maintaining and QA'ing this amount of packages is hard.

1. Incorrect versioning in Changelog(not adhering to SemVer specs)
   Package Version: 0.7.1-preview
   Changelog Version: 0.7.1
   Example
   Sometimes (rarely), it's even worse: [0.1.2-preview] - 9999-12-31
   Example

2. Internal submodules submitted with package releases
   Some packages contain .gitmodules and .git files.
   These show that internal submodules are used, e.g. for Testing:
   com.unity.test-framework.performance contains a .gitmodule with

[submodule "Runtime/Data"]
    path = Runtime/Data
    url = ../../../gintautas/unity.performancetesting.data.git

Of course it's totally ok that there are submodules for heavy test data, but embedding such a package in a project might cause some issues since the (Unity internal) submodule obviously can't be found.

1. No/empty changelogs
   Example - very helpful changelog
   Example - Changelog TODO
   Example - no Changelog

2. Some teams might need more information about package structure
   Example - four releases to get ~Documentation folder right

Overall, quality of Changelogs definitely increases over time — seems more and more teams are aware of how important a good changelog is. Thank you!

Open questions

We haven't fully understood how Unity determines which packages to show in Package Manager. For example, URP 6.x is only visible in Unity 2019.2, but not in 2019.3 or 2020.1 — package.json only specifies a min version, not a max version.

If someone knows, please tell us on Twitter!

Known Issues

Currently, it's not easy to see:

• which Unity version is supported by a specific package
  you can still see the minimal version from inside package.json, but not maximal version

• which package versions have been unpublished again.
  we might add a tag for that at a later point

• package keywords
  we'll have to add them manually as repository topics

Packages aliases

These have been renamed at some point

com.unity.renderpipelines = com.unity.renderpipelines.core  
com.unity.spriteshape = com.unity.2d.spriteshape  
com.unity.oculus = com.unity.xr.oculus  

Too big for our current automation approach

We will still update these, but less regular / manual

com.ptc.vuforia.engine  
com.unity.burst  
com.unity.xr.googlevr.ios  

Internal (can't access)

These show as "searchable packages" but aren't actually accessible

com.unity.package-manager-doctools  

Deprecated

Can't access anymore

com.unity.facebook-platform (?)  
com.unity.barracuda.burst (merged into Barracuda package)  

Who did this?!

needle — tools for unity @marcel_wiessler @hybridherbst

Addendum

Oh, and @UnityTechnologies, if you feel this is wrong, please tell us and we'll figure something out. We'd love to take this down if you provide the same level of access, to data that is already publicly available.