dartdoc.dart generate pubspec.yaml doesn't use Dart language versioning

@mit-mit

Split off from #70084, reported by @mit-mit

The logic in dev/tool/dartdoc.dart calculates package versions by writing a temporary pubspec.yaml file. This file doesn't have an SDK constraint, so it's language version is undefined.

  // Create the pubspec.yaml file.
  final StringBuffer buf = StringBuffer();
  buf.writeln('name: $kDummyPackageName');
  buf.writeln('homepage: https://flutter.dev');
  // TODO(dnfield): Re-factor for proper versioning, https://github.com/flutter/flutter/issues/55409
  buf.writeln('version: 0.0.0');

https://github.com/flutter/flutter/blob/master/dev/tools/dartdoc.dart#L53

@gspencergoog

\cc @gspencergoog @dnfield

The next two lines in the file are:

  buf.writeln('environment:');
  buf.writeln("  sdk: '>=2.10.0 <3.0.0'");

So, what is it that is missing?

@gspencergoog

Does pub do something strange when you put version 0.0.0?

This was done to work around the way dartdoc and firebase were interacting.

Basically, we want to avoid changing every generated doc file on every commit, since that means firebase has to hash and upload all of those files, which results in a lot of wasted space on the backend as well as much higher incidence of timeouts during uploads - i.e. the difference between uploading every bit of HTML at http://master-api.flutter.dev/ vs just uploading the HTML files that have changed since the last commit.

As @gspencergoog is saying, it looks like we are in fact writing the SDK constraint here, so it'd help to clarify what's missing.

/cc @mit-mit

The next two lines in the file are:

I believe I added those two lines writing an SDK constraint when I rolled the Dart SDK. Before that the pubspec had no SDK constraint at all.

Does pub do something strange when you put version 0.0.0?

No, that part is fine. The version number generally is only used for packages uploaded to pub.dev.

so it'd help to clarify what's missing.

I have to admit that I don't fully understand this dartdoc script, so take the following lightly:

With the lines writing the SDK constraint, we're hardcoding the language version to 2.10. There are two potential issues with this:

It becomes more likely that we forget to update this number should we need to. I'd suggest to put the pubspec "header content" into an actual pubspec.yaml file and then have this script read that. That way a simple search for pubspec.yaml make it much easier to find all pubspecs in the repo
It encodes a single language version for all packages in packages/, that overrides the language version they may themselves have in their pubspecs. Do we consistently use the same version all of them? We should also check that dartdoc currently generates the correct output for null safety, as it looks like some packages have 2.12 constraints.

Yes, we should probably do both of those things. I'm not sure what the correct language version to use would be, though: perhaps we pick the "newest" version in the packages?

Yeah, probably just read it out from packages/flutter/pubspec.yaml and use it from there.

Is this still an issue? I don't see any file at dev/tools/dartdoc.dart anymore

The script was renamed to create_api_docs.dart, but it still does something similar to before.

I'd also add that the second point (about null safety) is moot now that we're past that constraint (they are all null safe).

And, while putting it into a file named "pubspec.yaml" makes it more discoverable, it may also complicate tooling around flutter update-packages, since that manages all the pubspecs simultaneously, assigning them checksums, and would add a bunch of pinned constraints to any file named pubspec.yaml. This might be OK, and even desirable, but we'd need to take that into account, and if it turns out to be undesirable, we'll have to exclude any directory that includes that file from the update.

Use `$dartSdkVersion` when creating "dummy" pubspec for `create_api_d…

This thread has been automatically locked since there has not been any recent activity after it was closed. If you are still experiencing a similar issue, please open a new bug, including the output of flutter doctor -v and a minimal reproduction of the issue.

Use `$dartSdkVersion` when creating "dummy" pubspec for `create_api_d…

Navigation Menu

Repository navigation

dartdoc.dart generate pubspec.yaml doesn't use Dart language versioning #70239

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

dartdoc.dart generate pubspec.yaml doesn't use Dart language versioning #70239

Description

Activity

jmagman commented on Nov 10, 2020

gspencergoog commented on Nov 10, 2020

dnfield commented on Nov 10, 2020

mit-mit commented on Nov 11, 2020

gspencergoog commented on Nov 11, 2020

dnfield commented on Nov 12, 2020

eliasyishak commented on Oct 16, 2023

gspencergoog commented on Oct 16, 2023

gspencergoog commented on Oct 16, 2023

github-actions commented on Aug 4, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions