Clasp: Tag your Releases

[nmccready]

Expected Behavior

All releases on npm are tagged and in sync with git.

Actual Behavior

Tags are severely lagging and or not tagged on github.

This is important in tracking down bugs and stable versions.

[nmccready]

❯ yarn info @google/clasp
yarn info v1.5.1
{ name: '@google/clasp',
  description: 'Develop Apps Script Projects locally',
  'dist-tags':
   { latest: '1.1.5' },
  versions:
   [ '1.0.0',
     '1.0.1',
     '1.0.2',
     '1.0.3',
     '1.0.4',
     '1.0.5',
     '1.0.6',
     '1.0.7',
     '1.1.0',
     '1.1.1',
     '1.1.2',
     '1.1.3',
     '1.1.4',
     '1.1.5' ],

Github Tagged

1.0
1.1

[grant]

I've only tagged semi-major versions due to bandwidth.

• How important is GitHub tagging?
• Can you give an example of how to tag better?
• Are there any tools to make this automatic when I npm publish?

[nmccready]

If it were not important then I would not be here ;) .

npm version practically makes this automatic.

https://docs.npmjs.com/cli/version

[nmccready]

Also keep this in mind if you do not like npm's auto adding of the prefix v to tags.

https://docs.npmjs.com/misc/config#tag-version-prefix

.npmrc (local to project)

tag-version-prefix=''

[grant]

@nmccready Can you create a PR to change the README#publish section and/or package.json with these best practices?

I'd appreciate it!

[rafasc]

Based on changes to package.json version string, these are the commits that correspond with versions bumps.

git log -L /version/,/$/:package.json
---
Edit: Deleted table, updated in comment below.

[rafasc]

The problem is especially evident if you compare with commits reported by npm. Which I assume are the correct ones.

for v in $(npm v @google/clasp versions --json | jq -r .[]); do 
    printf -- '%s : %s\n' $v $(npm v @google/clasp@$v gitHead)
done

| Version | npm | package.json | match? |
|:----------:|:-----:|:-----------------:|:------------:|
| 1.0.0 | 10d380a51fe8b6ae7011f437bbd852cf8e381e1c | b31a4db2403005754bc15ec66dcb0fcfe552f69c |❌|
| 1.0.1 | 09181de53935f6340a5a554538781abedb5a023c | 09181de53935f6340a5a554538781abedb5a023c |✔️|
| 1.0.2 | 3126c767cdaaf50ffe314a9e307db373d4743e9d | 3126c767cdaaf50ffe314a9e307db373d4743e9d |✔️|
| 1.0.3 | 8f622ebbe0508c3e6d1e06befc8b4a2b47aa6867 | 8f622ebbe0508c3e6d1e06befc8b4a2b47aa6867 |✔️|
| 1.0.4 | 5908791540f668983797348188cc08369f208f14 | 72ac58c0961cf2609d0b53f742d5a9aab4a1b43a |❌|
| 1.0.5 | a07cae6d5c50d34aed357034ae7660ef165d88f3 | a07cae6d5c50d34aed357034ae7660ef165d88f3 |✔️|
| 1.0.6 | 31c1aed390929c4863a0b483d5dbd3ceba262cbf | 31c1aed390929c4863a0b483d5dbd3ceba262cbf |✔️|
| 1.0.7 | 1ec3c4ff8fe02646b743017424a8046287b9c101 | 1ec3c4ff8fe02646b743017424a8046287b9c101 |✔️|
| 1.1.0 | ccaa1fa5cc850b6b7fcf26a0c6dbbe05c820b81f | 77dc7e292e63ff73faf11ddcb97edd3fc73e3e38 |❌|
| 1.1.1 | a39eb4b1b2104d006f6265d904d312d3e4bc6f84 | a39eb4b1b2104d006f6265d904d312d3e4bc6f84 |✔️|
| 1.1.2 | 697562293c7d83372c4248dcb237abbdc3caf175 | 697562293c7d83372c4248dcb237abbdc3caf175 |✔️|
| 1.1.3 | e26e0194d876739156aa160b316f8df6ce71e926 | e26e0194d876739156aa160b316f8df6ce71e926 |✔️|
| 1.1.4 | abd4aa5e46d43f268f75a1f9e4152280675abb74 | abd4aa5e46d43f268f75a1f9e4152280675abb74 |✔️|
| 1.1.5 | e739283a1a27f387d28af184c7b1acbbefaae245 | e739283a1a27f387d28af184c7b1acbbefaae245 |✔️|

I've only tagged semi-major versions due to bandwidth.

I don't understand this. Git tags are small.
Please try use annotated/signed tags for future and past versions. This ambiguity doesn't need to exit.

[grant]

I'll keep this issue open and backfill the tags for the missing versions on npm.

[rafasc]

1.3.2 tag and release is also missing.

[rafasc]

Following the advice on #220 solves the problem with future tags, as npm version already makes annotated tags by default. Past tags are still lightweight, and per https://github.com/git/git/blob/master/Documentation/git-tag.txt#L52-L55, no suited for releases.

[grant]

Hey @nmccready @rafasc,
As stated in https://github.com/google/clasp/issues/64#issuecomment-373164425, I added git tags to the updated versions that weren't there before (just now).

I hope to use the instructions @rafasc (#220) set for bumping versions. I'm sorry the previous versions aren't in sync. Do you think we can close this issue and follow best-practices in the future, or is there anything else we should do?

[nmccready]

@grant looks much better but it looks like 1.4.0 got released via another method as there are some inconsistent tagging names (w vs w/o "v").

❯ git tag
1.0.1
1.0.2
1.0.3
1.0.4
1.0.5
1.0.6
1.0.7
1.1.1
1.1.2
1.1.3
1.1.4
1.1.5
1.2.1
1.3.2
1.3.3
v1.0
v1.1
v1.2
v1.3
v1.3.1
v1.4.0

~/code/thirdparties/clasp master
❯ npm info @google/clasp

{ name: '@google/clasp',
  description: 'Develop Apps Script Projects locally',
  'dist-tags': { latest: '1.4.0' },
  versions:
   [ '1.0.0',
     '1.0.1',
     '1.0.2',
     '1.0.3',
     '1.0.4',
     '1.0.5',
     '1.0.6',
     '1.0.7',
     '1.1.0',
     '1.1.1',
     '1.1.2',
     '1.1.3',
     '1.1.4',
     '1.1.5',
     '1.3.0',
     '1.3.1',
     '1.3.2',
     '1.3.3',
     '1.4.0' ],

[nmccready]

Also as mentioned in previously ☝️ I would commit an .npmrc file to enforce the release pattern .

To be more explicit this file would be added to the root of this repo ./.npmrc and the settings for .npmrc locally take precedence over the ~/.npmrc.

[rafasc]

@grant Did you bump to v1.4.0 using the proposed workflow? If yes, there might be an issue because, v1.4.0 isn't annotated tag.

$ git tag -l --format='%(objecttype):%(refname:short)'
tag:1.0.1
tag:1.0.2
tag:1.0.3
tag:1.0.4
tag:1.0.5
tag:1.0.6
tag:1.0.7
tag:1.1.1
tag:1.1.2
tag:1.1.3
tag:1.1.4
tag:1.1.5
tag:1.2.1
tag:1.3.2
tag:1.3.3
commit:v1.0
commit:v1.1
commit:v1.2
commit:v1.3
commit:v1.3.1
commit:v1.4.0

there's also the inconsistency about the v prefix as @nmccready pointed out.
I don't have a preference, as long as it's kept consistent.

[rafasc]

There are still some minor issues in my opinion.

|version from registry| gitHead from registry| tag in repo | sha | issues|
|--|--|--|--|--|
| 1.0.0 | 10d380a51fe8b6ae7011f437bbd852cf8e381e1c |v1.0 | e428501117b8520cb2fe0b3c77f8c8bc33a25317 | 1 2 3 |
| 1.0.4 | 5908791540f668983797348188cc08369f208f14 |1.0.4 | 72ac58c0961cf2609d0b53f742d5a9aab4a1b43a | 2 |
| 1.1.0 | ccaa1fa5cc850b6b7fcf26a0c6dbbe05c820b81f |v1.1 | ccaa1fa5cc850b6b7fcf26a0c6dbbe05c820b81f | 1 3 |
| | |v1.2 | 23b74d895006f412af5b991ea10cfc663f8d9942 | 1 4 |
| | |1.2.1 | 3b56999b895e687406a8d5d8cd51d197d4792748 | 4 |
| 1.3.0 | 24c7d1309cde125b7a9db2a7d41f32bab4f5d7d1 |v1.3 | 24c7d1309cde125b7a9db2a7d41f32bab4f5d7d1 | 1 3 |
| 1.3.1 | 6d448753ed4f1ffbb098f4847cafda939836b07b |v1.3.1| 6d448753ed4f1ffbb098f4847cafda939836b07b | 1 3 |
| 1.4.0 | 0ce9d5dfef1198a16290db96f6987778df4b86b5 |v1.4.0| 0ce9d5dfef1198a16290db96f6987778df4b86b5 | 1 3 |

1: tag in repo is not annotated.
2: tag in repo points to a different commit than registry.
3: tag format differs from registry (minor issue, if it was done consistently)
4: tag exists in local repo, but not in registry (minor issue, could be intentional: tagged but not released)

For reference, registry was queried using:

#!/usr/bin/bash

curl --silent 'https://registry.npmjs.org/@google/clasp' \
  | jq -r '.versions[] | .version+" "+.gitHead' \
  | while read -r version sha; do
    echo $version $sha
    done;

Check if annotated:
git tag -l --format='%(objecttype) %(refname:short)'

sha tags are referencing:
$ git tag -l --format='%(refname:short) %(if)%(tag)%(then)%(object)%(else)%(objectname)%(end)'

---

Since the backfilled tags were added without the v prefix, I'll assume that's the desired format. @nmccready Can you open a PR that adds the .npmrc to enforce versions without the v prefix?

Solving the v1.0 and 1.0.4 mismatch would require overwriting tags, which is usually considered bad practice. I suggest leaving 1.0.4 as is since 5908791 is actually the parent of 2822fbf. So nothing really important is lost there.

v1.0 on the other hand, actually comes after 1.0.5. This is really confusing, especially when you use something like --contains from certain git commands, or git describe.

So I suggest getting rid of it. And since we're biting the bullet, might as well delete all the other v-prefixed ones and keep it consistent by replacing vx.x with x.x.0.

@grant Sorry about being so pedantic about this.

[grant]

I'll eventually get used to tagging.
Keeping this open until it's fixed. Thanks for the details.

[nmccready]

Since the backfilled tags were added without the v prefix, I'll assume that's the desired format. @nmccready Can you open a PR that adds the .npmrc to enforce versions without the v prefix?

10-4

[nmccready]

Done for .npmrc https://github.com/google/clasp/pull/243

[rafasc]

Seems that there was another mishap with 1.5.1.

@nmccready For my personal use, I added tags that match the registry to my fork. Following the npmjs/clasp-X.X.X format, so they can happily live alongside the existing ones.

They don't have any real value because they're tagged by me, but for convenience you can get them from there by using git fetch --tags https://github.com/rafasc/clasp or by adding it as another remote and fetching from it.

[rafasc]

The entire 1.6.x series was correctly tagged and there's limited things we can do about past ones. I think this issue can be closed.

[grant]

OK, Thanks @rafasc.
I don't manually modify the package.json version attribute, so hopefully future ones are fixed with the npm script setup.