Publish on OpenUPM

[favoyang]

Hi @sarkahn,

Thanks for creating the awesome project. I'd like to include it to the OpenUPM platform, an open source Unity package registry with automatic build pipelines that bundle UPM package based on semver git tags. Here's the announcement blog for more details.

Your package is well structured, the only thing missed is a GitHub release (git tag, like 1.0.0 / v1.0.0).

• The easier way is to create release manually via GitHub releases page.
• Or use semantic-release to automate it (but it requires you change your commit message style).

[sarkahn]

Hi! Thanks for the interest, it sounds promising. Currently I'm using travis CI to automatically restructure my master branch from how it is now (the "normal" unity project style of Assets/ProjectSettings/Packages in the root folder) to a UPM friendly structure (Runtime/Samples~/Editor etc) in the root folder. It's a bit awkward so I wouldn't mind something a littler simpler.

Is this something openupm can do? I need to be able to rename certain folders for the UPM branch ("Samples" folder in master to "Samples~" in UPM branch) so that the samples show up properly for import in the package manager.

[favoyang]

Hi @sarkahn,

I'm not using Travis CI, but I checked the script:

1. create upm branch based on Assets folder
2. rename Samples folder to Samples~
3. move some documentation files like README, CHANGELOG to the upm root. But somehow they do not appear in the current upm branch?

These can be replaced with GitHub actions. 1/2 are already supported in this tutorial. 3 need some efforts but achieve-able.

OpenUPM build pipelines will not do these customize build jobs for you. It's better leave it to the CI. Our build pipelines simply watch new git tags that match semver, and bundle packages to publish to the registry.

Since you already have the CI setup, the key question is whether you'd like to move to a continuous releasing strategy to automate the release process.

• If yes, you can follow the example project https://github.com/favoyang/semantic-release-upm-example to install semantic-release. The example project is using GitHub actions. It doesn't handle the documentation files, but we can solve it later on.
• If not, you can manually create GitHub releases from your upm branch.

Update: fixed the wrong tutorial link.

[sarkahn]

Understood, thank you very much for the detailed response! I will take a look at some point in the next few days.

[reeseschultz]

@sarkahn, just dropping in to plug ubump for your SemVer needs, which is specifically built for Unity projects and UPM packages.

I built ubump to support my UPM package monorepo, which will start officially using it in a couple days (I just released the utility last night). ubump syncs all the dependencies between the main project's manifest.json file so I, at least, stop forgetting to update them. It also creates Git subtree branches for all bumped packages (unless the package.json is at the root of the project—I may make this logic more nuanced later). It includes annotated tagging with proper changelog messages, but I still need to automate changelog markdown generation.

To use ubump, just cd to your project directory and run npx ubump. It's that simple.

And that's just for the interactive CLI—you may prefer to use the non-interactive CLI in CI or something. Just thought I'd bring this to your attention if it helps. I'll be attentive to raised issues, updating ubump quite a bit over the next few weeks to ensure it's resilient, but the test coverage for the core API is already at ~90%. Also, @favoyang if there's some way I can make ubump more OpenUPM-friendly, please let me know.

[favoyang]

Hey @reeseschultz,

Thanks for making ubump. It looks like a combination of lerna + release-it or semantic-release. It's mostly designed for monorepos, but can also work for single repo.

For OpenUPM, it simply watch git tags that match semver format to publish packages. Like 1.0.0, v1.0.0, as well as a path-like prefix upm/1.1.0, releases/stable/1.1.0, whatever/1.1.0.

For monorepos,

• multiple package submissions are required (multiple yaml files).
• if ubump can use path-like prefix for git tags, it will just work. i.e. for monorepos with packages namespace.a and namespace.b, the git tags could be namespace.a/1.0.0 and namespace.b/1.0.0.
• one thing OpenUPM can improve is adding a git tag prefix field to filter git tags. So package namespace.a will ignore namespace.b/1.0.0 git tag to avoid wasting the CI resource. (record as openupm/openupm#69)

[reeseschultz]

@favoyang Thankfully ubump already uses the path-like syntax for tags, so com.foo.bar would result in an bar Git subtree branch, and releases to that branch would result in tags of the form bar/v*.*.*. The main project, or if there's just one package at the root, results in no subtree branches, but it is tagged on master (by default, anyway) in the form of v*.*.*. If any of this logic should change, please submit more issues in the ubump repo and I'll get things updated.

[favoyang]

@reeseschultz Perfect

One last thing on this thread. I have fixed openupm/openupm#69. Would you mind use your ubump on https://github.com/reeseschultz/ReeseUnityDemos to create releases? Then you can submit to OpenUPM separately, see more in https://openupm.com/docs/adding-upm-package.html#handling-monorepos

[reeseschultz]

Absolutely. I'll start using ubump with ReeseUnityDemos soon. I'll submit to OpenUPM afterward. Also sorry @sarkahn for going on a tangent with some slightly unrelated stuff.

[sarkahn]

@favoyang Sorry it took a while but I've finally gotten around to this - I've created a test package and I was following your tutorial. It worked great up until I tried to integrate semantic-release. It seems like it can't find my package.json file, I'm not sure what I'm doing wrong:
https://github.com/sarkahn/test_actions/runs/484347712?check_suite_focus=true

My .releasesrc.json is at https://github.com/sarkahn/test_actions/blob/master/.releasesrc.json. As far as I can tell I set up the paths properly but it still errors out during the step. Any help would be appreciated.

[favoyang]

Hi @sarkahn,

It caused by a mistake that .releasesrc.json should be .releaserc.json (not plural).

BTW, if you want to debug locally.

1. Install semantic-release

npm install -g semantic-release @semantic-release/changelog @semantic-release/git

2. Request a GitHub token, record it somewhere.

https://github.com/settings/tokens

3. Dry-run

GH_TOKEN=YOUR_TOKEN semantic-release -d

4. Looks good? Commit to git.

[sarkahn]

@favoyang Wow, thank you, that's what I get for staying up so late.

I got it working but I'm trying to tweak it a bit and hitting another roadblock. I want to have my CHANGELOG/LICENSE/README from the root folder included with the package repo. I tried changing the path to the changelog in .releaserc.json:

    ["@semantic-release/npm", { "npmPublish": false, "pkgRoot": "Assets/CoolPackage" }],
    ["@semantic-release/git", {
      "assets": ["Assets/CoolPackage/package.json", "Assets/CoolPackage/CHANGELOG.md"],
      "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
    }],

But that doesn't work - it won't write the updated changelog to that file and it causes the CI to fail during the checkout step:

I tried adding -f to force the checkout and it just causes it to silently fail just before pushing the branch.

I was thinking I could just keep the files in the project root and copy them before the subtree split but then they wouldn't have the accompanying meta files unless those files were already in the package root. Without the meta files it would probably cause console warnings on package import.

Any suggestions on how to solve this?

[favoyang]

According to https://github.com/semantic-release/changelog, you can try specify the changelogFile parameter for @semantic-release/changelog step.

    ["@semantic-release/changelog", { "preset": "angular", "changelogFile": "Assets/CoolPackage/CHANGELOG.md" }],

[sarkahn]

@favoyang Thanks for all the help and your great tutorial, I think I finally got it all set up correctly.

Regarding copying the readme/license/changelog files from the project root to the package root before branching - I tried it and it did indeed cause errors on package import due to missing .meta files. I'll have to think about a better solution.

[favoyang]

Regarding copying the readme/license/changelog files from the project root to the package root before branching - I tried it and it did indeed cause errors on package import due to missing .meta files. I'll have to think about a better solution.

A few dirty solutions 😑

1. Create dummy readme/license/changelog files in the master Assets/ folder to generate the meta files, then override them as you did in a recent commit.

2. Write a custom script to generate unity meta files, to keep consistent you need specify the uuid manually

# something like this
npx unity-uuid gen <filename> [uuid]