search

apiaryio / api-elements.js

Library for consuming API Elements in JavaScript
https://apielements.org/
MIT License
75 stars 18 forks source link

Package Naming #32

Open kylef opened 5 years ago

kylef commented 5 years ago

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:

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 commented 5 years ago

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:

...and

@apielements/* - @apielements/cli = apielements

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

Almad commented 5 years ago

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

pksunkara commented 5 years ago

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

kylef commented 5 years ago

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 commented 5 years ago

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

kylef commented 4 years ago

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

Fury, the remote adapter and cli:

opichals commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

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 commented 3 years ago

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