Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reconsider one package vs. multiple packages #299

Closed
xvrh opened this issue Jan 5, 2021 · 8 comments · Fixed by #394
Closed

Reconsider one package vs. multiple packages #299

xvrh opened this issue Jan 5, 2021 · 8 comments · Fixed by #394
Labels

Comments

@xvrh
Copy link
Collaborator

xvrh commented Jan 5, 2021

I'd like to re-open the discussion about single vs several packages.

I read the discussion of last year here: #63
The main reason to split the apis in several packages was to prevent the documentation generation to timeout on pub.dev.

I personally think that the advantages of the single package option outweighs this small inconvenience.

Pros of a single package:

  • Easier development (simplify code generator etc...)
  • Easier publishing
  • Easier to add/remove APIs
  • A user of the library have immediately access to all the apis (like in JS and Python)
  • Easier to work with git and dependency_overrides
  • ...

Cons:

  • Possibly no documentation on pub.dev (mitigated by publishing our own documentation)
  • Some users may only use one API and don't want to download the code for the others?

Proposal

Here is my rough idea on how we could possibly proceed

New package

Publish a new package (aws_client?) that contains all the apis.

Layout:

lib/
  src/
    shared/ // Content of the shared_aws_api
    accessanalyzer/
      2019-11-01.dart // actual code
      2019-11-01.g.dart
  accessanalyzer/
    2019-11-01.dart // export src/accessanalyzer/2019-11-01.dart
    ...
README.md: generated list of all apis with a small description (ie. https://pub.dev/packages/googleapis)
CHANGELOG.md: hand-edited changelog with global improvements

Migration

Publish a new version for all current packages with an updated README pointing to the new single-package.
Discontinue all the previously published packages on pub.dev

Documentation

Mitigate the pub.dev timeout failure by publishing our own documentation and link to it in the README.
When we tag the repository, a Github Action runs dartdoc and upload the new doc on github.io.

Longer term: profile the execution of dartdoc on the package to understand how to speed it up (currently it takes 15 minutes on my mac with the all_apis package).

WDYT?

@Schwusch
Copy link
Collaborator

Schwusch commented Jan 5, 2021

I suppose it doesn't hurt to try it.
What I'm wondering is how we should export the classes on our part, and how the users import them in their applications.
How easy will it be to find the correct service/class?
Perhaps if we create the package on this repo without publishing, we can try it out :)

@isoos
Copy link
Contributor

isoos commented Jan 5, 2021

Possibly no documentation on pub.dev (mitigated by publishing our own documentation)

I can try to lobby for putting the package (and other similar large packages) on an exception list with longer timeouts (possibly only for the latest stable version).

@xvrh
Copy link
Collaborator Author

xvrh commented Jan 5, 2021

Thanks for your input!

Let's experiment. As a first step, I'll modify the generation of the all_apis package with the layout I propose.
The way I see it, the imports will be:

import 'package:aws_client/s3/2006-03-01.dart';
import 'package:aws_client/apigateway/2018-11-29.dart';

The autocompletion will show all the available services at first and then the available versions.

@Schwusch
Copy link
Collaborator

Schwusch commented Jan 15, 2021

I'd like to point out that aws-sdk-js V3 is generating(!) separate packages.

@xvrh
Copy link
Collaborator Author

xvrh commented Jan 16, 2021

@Schwusch This is a very interesting discovery!!

I have experimented with the single package structure here: https://github.com/xvrh/aws_client/tree/master/aws_client/lib
I understand it's mainly a matter of taste and I don't want to push it in that direction if your are not convinced :-)

@Schwusch
Copy link
Collaborator

I have experimented with the single package structure

That looks incredibly clean I must admit!

I dug further into aws-sdk-js-v3, and apparently they use something called Smithy to generate the clients. Smithy is language agnostic, so they use smithy-typescript to generate the JS SDK. Which makes me wonder if it would be worth looking into making a smithy-dart to get all the juicy type information we need for Darts null-safety.

@Schwusch
Copy link
Collaborator

I would say, the only way of knowing if this is a viable alternative is to publish a package with all the services in it.
Since there is the option to mark a package discontinued and/or unlisted, I think it's worth a try.

It would probably solve the dependency problem I faced when resolving credentials with STS in #328.
There, it was problematic to use STS in the shared package, since STS in itself depends on the shared package.
If all code resided in the same package, perhaps that wouldn't be a problem.

If you feel like trying it out, I would say go for it :) If it's successful and appreciated, perhaps we can go in that direction instead.

@Schwusch
Copy link
Collaborator

Schwusch commented May 3, 2022

makes me wonder if it would be worth looking into making a smithy-dart to get all the juicy type information

It seems @dnys1 is working on a smithy-dart implementation already.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants