Package Naming

[kylef]

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

[honzajavorek]

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?)

[Almad]

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

[pksunkara]

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

[kylef]

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.

[pksunkara]

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

[kylef]

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)

[opichals]

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.

[kylef]

@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).

[opichals]

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?

[feczo]

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