Shields: version 3 roadmap for npm package

[chris48s]

As mentioned in https://github.com/badges/shields/pull/3507 there are a number of changes we've discussed to the NPM package which are not backwards-compatible. It makes sense to batch them into a version 3.

• [x] Validate inputs (done in #3875 )
• [x] Remove legacy properties deprecated in 2.2.0 (done in #3881 )
• [x] Replace the BadgeFactory class with a single function (done in #3884 )
  
  
  
  • Now that we're using anafanafo for text measurement, we don't need the class wrapper anymore
  
  
  • See https://github.com/badges/shields/pull/2336
  
  
• [ ] Expose the concept of logos, add SimpleIcons as a peer dependency (this is actually just a new feature not a BC break, so we could push this back to a minor, but its probably nice to think about in this block of work)
• [ ] Depend on the public interface internally instead of relative imports
• [ ] Publish the package to a new/better name, change repo dir, mark gh-badges dead/unmaintained
  
  
  
  • See https://github.com/badges/shields/pull/2300#issuecomment-438034266
  
  

Anything else that should be on that list?

[calebcartwright]

If we change the package name (which I'm in favor of), does it make sense to start it with major version 3? I'm not sure what the semver protocols are for renamed packages.

It's probably best to keep it v3.x to avoid confusing existing users of gh-badges w/2.x or 1.x though right?

[paulmelnikow]

Your list looks good! 👍

Two I might add:

• [x] Make dependencies for raster support optional (this will make the installed / bundled footprint much smaller)
• [x] Finish converting to template strings, dropping DoT (#2428)

I agree with keeping the version scheme the same so the new package would still be 3.x. It'll be the same library, with a new name.

[chris48s]

one more..

• [x] Either drop raster support from the CLI or add it to the library (see https://github.com/badges/shields/pull/3586#discussion_r295802787 , https://github.com/badges/shields/pull/3875#discussion_r314467517 for discussion )

[calebcartwright]

What about adding a typedef file to the package to make it easier to use from TypeScript (assuming there isn't already one under DefinitelyTyped)?

[chris48s]

Presumably adding typescript defs is a non-breaking change, in that consuming them is optional? If so, we could add it in a minor.

As I've got into the v3 work, I'm already starting to think logos might be better pushed back to a minor too so we can limit 3.0 to just the non-backwards-compatible stuff.

[calebcartwright]

Presumably adding typescript defs is a non-breaking change, in that consuming them is optional? If so, we could add it in a minor.

Sure! I'd personally prefer to avoid having to create a typedef for the current/v2 API given the deprecation plans for v3, but I don't have any objections to creating and including a v2 typedef in a minor bump too

[chris48s]

Aah sorry. I was thinking more that we can make only the non-backwards-compatible changes in 3.0 but typedefs (for v3) could be added in a 3.1 (or 3.x), as opposed to doing a 2.3 release with typedefs.

[chris48s]

Reviewing this, the remaining tasks are:

1. Either drop raster support from the CLI or add it to the library (I'll come back to this one..)
2. Expose the concept of logos, add SimpleIcons as a peer dependency (this is a new feature, so lets punt it to 3.1)
3. Add typescript definitions (this is a new feature, so lets punt it to 3.1)
4. Change the application code to depend on the public interface internally instead of relative imports (this isn't essential to get 3.0 done but its pretty small so I'll just do it)
5. Publish the package to a new/better name, change repo dir, mark gh-badges dead/unmaintained (We'll look at this in the final PR from v3-dev to master. I'll also finalise the docs/changelog, etc in this PR)

..so the remaining big thing is point 1: Either drop raster support from the CLI or add it to the library (or just ignore it and leave things as they are).

We never really reached an agreement on this, so I did both and submitted 2 competing PRs:

• #4523 - Drop raster support in package CLI
• #4524 - Support raster formats in makeBadge

Seeing both implementations might help us reach a decision. I think having seen what supporting the raster formats in makeBadge() looks like, I think my preference is to drop it in both, or just leave it as it is (CLI supports raster, but makeBadge() doesn't)

The other thing to think about is point 5 - changing the package name. I'm sure we've discussed this, but I'm coming up blank trying to find the conversaions:

• Did we agree on a new name for the package? I know we don't like gh-badges, but I can't remember if we decided on a replacement.
• Should we start numbering from 3 on the new package name, or go back to 1?
• I think it would be a good idea to do one final gh-badges release which just adds a changelog entry advising users to switch to the new package _before_ we deprecate it on NPM. The reason I suggest this is that dependabot (and probably other tools) don't offer upgrades to deprecated packages (see https://github.com/dependabot/feedback/issues/163 ) so I reckon doing one final release communicating the change will give us the maximum chance of communicating the change to users who rely on automated tooling for dependency management.
• I'd also like to get shields.io running the latest package code in production before we do a _stable_ release of the new package just so we've done some in-the-wild testing.

[calebcartwright]

Seeing both implementations might help us reach a decision. I think having seen what supporting the raster formats in makeBadge() looks like, I think my preference is to drop it in both, or just leave it as it is (CLI supports raster, but makeBadge() doesn't)

Should we also try to poll the community for feedback and to gauge importance? We did when making a similar change for Shields.io, although that's admittedly a larger audience that was impacted

[calebcartwright]

I think it would be a good idea to do one final gh-badges release which just adds a changelog entry advising users to switch to the new package before we deprecate it on NPM.

Agreed. I can't find any examples ATM, but I know I've seen a final version publish that adds a pointer/doc to the top of readme pointing to the "new" package on some other packages that were renamed. Something like..

gh-badges as been renamed to [foo](new package url)...

Should we start numbering from 3 on the new package name, or go back to 1?

I thought we'd agreed on starting with v3. That'd be my preference/vote anyway

Did we agree on a new name for the package? I know we don't like gh-badges, but I can't remember if we decided on a replacement

Not that I know of/remember. Naming things is so hard 😄

[chris48s]

I will review this issue tomorrow or at the weekend, pick out the bits we didn't do into new issues and close this.

[chris48s]

I've split the remaining future work from this issue into more specific issues