api-elements.js icon indicating copy to clipboard operation
api-elements.js copied to clipboard

Published 20 hours ago • verified publisher icon apiaryio

Package Naming

Open kylef opened this issue 6 years ago • 10 comments
trafficstars

We should settle on the package naming going forward along with how we will package adapters up as we can also use NPM Scoped packages https://docs.npmjs.com/misc/scope (@apielements/openapi etc). We have the following packages at the moment:

  • minim-api-description
  • minim-parse-result
  • fury
  • fury-cli
  • fury-adapter-apib-parser
  • fury-adapter-apiary-blueprint-parser
  • fury-adapter-swagger
    • swagger-zoo
  • fury-adapter-apib-serializer

Perhaps the adapters could become something like @apielements/openapi2-parser, @apielements/openapi3-parser, @apielements/apiblueprint-parser. We could offer @apielements/cli and some package containing the base (fury.js) and namespace.

We could also offer a root level package apielements which provides everything, it could provide all of the adapters that we provide along side the CLI tool. That way consumers like Dredd (@honzajavorek), and Documentation (@char0n) have a single dependency use apielements which has all of the provided adapters already included without them having to deal with each adapter.

I know @honzajavorek had some gripes with using a dash in api-elements package so we can settle that too. I'd appreciate any feedback on the naming convention here.

/c @pksunkara

kylef avatar Dec 07 '18 22:12 kylef

Yup, I like apielements more than api-elements, the dash seems to be redundant as even without it the name reads well, but types better.

I'd perhaps keep the CLI separated from the rest, i.e. the apielements package wouldn't contain it by default. I believe the use cases are different and the CLI is more of a convenience tool for developers than something one would need to have in their production dependencies. Otherwise it seems to be a good idea:

  • minim-api-description → ?
  • minim-parse-result → ?
  • fury → @apielements/core
  • fury-cli → @apielements/cli
  • fury-adapter-apib-parser → @apielements/apiblueprint-parser
    • mson-zoo → @apielements/mson-examples ?
  • fury-adapter-apiary-blueprint-parser → @apielements/apiaryblueprint-parser
  • fury-adapter-swagger → @apielements/openapi2-parser
    • swagger-zoo → @apielements/openapi2-examples
  • fury-adapter-apib-serializer → @apielements/apiblueprint-serializer

...and

@apielements/* - @apielements/cli = apielements

...but then I'd also rename this repo so it is apielements (.js?)

honzajavorek avatar Dec 10 '18 12:12 honzajavorek

May be worth bringing up on brainstorm / TLS / @w-vi since I think this would be good to unify across the board.

Almad avatar Dec 10 '18 18:12 Almad

Do we have to support the previous names for backward compatibility? I mean, do we still publish to previous package names.

pksunkara avatar Dec 11 '18 09:12 pksunkara

I'd make a final release with old names and then deprecate the packages encouraging users to migrate to the newer ones. We should release a near-identical version under both names so people can move to the newer named packages without having to worry about other breaking changes to handle at the same time.

Thus, we should get the current minim/Fury release completed before we rename the packages.

kylef avatar Dec 12 '18 21:12 kylef

@kylef This was wrongly closed because of moving OAS3 I think.

pksunkara avatar Jan 23 '19 11:01 pksunkara

Fury Adapters will now be in the form @apielements/{format}-{type}, so that:

  • @apielements/apib-parser (formerly fury-adapter-apib-parser)
  • @apielements/apib-serializer (formerly fury-adapter-apib-serializer)
  • @apielements/apiaryb-parser (formerly fury-adapter-apiary-blueprint-parser)
  • @apielements/openapi2-parser (formerly fury-adapter-swagger)
  • @apielements/openapi3-parser (formerly fury-adapter-oas3-parser)

Fury, the remote adapter and cli:

  • @apielements/core (formerly fury)
  • @apielements/cli (formerly fury-cli)
  • @apielements/remote (formerly fury-adapter-remote)

kylef avatar Apr 29 '20 13:04 kylef

It would also be nice to be able to get npx @apielements/cli working without the need to do npm install @apielements/cli first. That works for dredd but never worked for fury-cli as the bin script was actually named fury.

opichals avatar Apr 29 '20 14:04 opichals

@opichals that's a good point, we'll figure out those details. Initially I will bump the name and keep same CLI binary (so migration is simpler, then issue breaking changes separately such as renaming CLI binary etc).

kylef avatar Apr 29 '20 14:04 kylef

then issue breaking changes separately such as renaming CLI binary etc

That might possibly be accomplished without a breaking change by introducing additional binary (same content) next to the existing one?

opichals avatar Apr 29 '20 15:04 opichals

Now that fury-cli is renamed to cli there are some broken pointers: for instance from https://github.com/apiaryio/swagger2blueprint

feczo avatar Jun 30 '21 05:06 feczo