allow automatic upload of CM information with packages

[jcollins-g]

@mit-mit @isoos

Dartdoc now supports linking directly to source code for generated API documentation. However, in order for this to work with the pub site, users have to autogenerate dartdoc_options.yaml files themselves with the necessary revision and linking information, and upload them with the package.

For a common case, uploading a package to pub from a github-backed repo for a package, it seems there should be some way to make this easier. It will probably require a design that spans dartdoc, pub, and the pub site.

[isoos]

/cc @jonasfj @sigurdm

[jonasfj]

Wouldn't it be easier to do source-listings as part of dartdoc generated output?

Using github source listings has a few downsides:

• People might not be publishing from github.
• Published files may contain generated code.
• Some packages are organized into mono_repo repositories, (e.g. build, protobuf and friends)
• We do not require or even encourage that developers tag their revisions when publishing to pub.
• Source listings on github doesn't have cross-referencing links or code search (Personally, I find dart code impossible to read without cross-referencing links, due to lack of package namespaces like golang).
• Source listings are likely to be used for quick security reviews, allowing package authors to falsify the listings is problematic.

I think it would be great to encourage revision and path in pubspec as well as tagging on github. But even if we had such linking, I'm not sure we would use it for source listings, due to the considerations listed above.

[jcollins-g]

@jonasfj It would be easier to do source listings as part of dartdoc output, and dartdoc already does that. The case for direct linking to github is primarily about making contributions to documentation easier and was strongly requested by Flutter. While I have it working for Flutter (and now, the Dart SDK as well), this issue is specifically about pub and the pub site.

We can of course choose not to support this in any better way in pub and leave it up to individual package owners to add support for it if they want. But I don't think any of the items you listed are more than requirements or caveats for any solution we might design. The question I have is -- is this desirable from a pub site user perspective? Since Flutter requested this feature so strongly it seemed logical that it would improve the pub ecosystem too if more widely available.

[jonasfj]

source listings as part of dartdoc output, and dartdoc already does that.

It only does this for exported libraries.. you can't click links and drive into the source of a package.. at-least on not pub, maybe that's an option that's turned of...

On topic: the idea that there is a button you can click which sends you to a place where you can edit code and submit a PR is pretty cool. GitHub always has this logic, you're right we just need to link to it. But in that case do you want to be sent to the revision that was published, or to the current master branch?

Hmm, making nice tooling to support better GitHub integration would be nice. IMO the way to do it would be to support publishing through a GitHub integration that reads tags. That would also encourage people to make tags :)

That said, @siguardm was arguing that rather than designing a GitHub integration, we could just make the pub publish command warn if:

• You have dirty state in got
• You have tagged the current checkout
• The tag haven't been pushed.

I suppose offering to inject metadata about repository and revision into the published pubspec.yaml wouldn't be much of a stretch, then pub could generate the dartdoc arguments.

[isoos]

It would be easier to do source listings as part of dartdoc output, and dartdoc already does that.

Slightly related: I think linking to a git repository tag/branch is always a short-term solution, because package content is supposed to be immutable, while a git repository (or the domain that hosts it) is not. Ideally we'd like to have a source browsing capability that is tied to the (immutable/fixed chain of) dependencies of the package at the time of the source code is generated, and dependent library sources are linked the same way. We should be able to navigate the sources (of a dependency) even if it is not hosted in a git repository, only published as a package.

It would be nice if dartdoc could support this, but it may be out-of-scope and should be a separate tool.

[jcollins-g]

@jonasfj

That said, @siguardm was arguing that rather than designing a GitHub integration, we could just make the pub publish command warn if:

• You have dirty state in got
• You have tagged the current checkout
• The tag haven't been pushed.

I suppose offering to inject metadata about repository and revision into the published pubspec.yaml wouldn't be much of a stretch, then pub could generate the dartdoc arguments.

Yes. Something along these lines sounds reasonable to me. I think we could make that simple and predictable enough for the user.

@isoos Dartdoc used to support such a tool, called crossdart, except once it was built it had minimal uptake because it wasn't GitHub. :-( We only recently stripped the last vestiges of it out of dartdoc. While I agree that such a tool would be good for correctness, evidence suggests that strict correctness is not the most important feature here -- linking to GitHub and/or other source tools the user already uses is.

As an aside, Dartdoc's support handles whatever URI templates the user has. So assuming you can link to it on the public interwebs, it's possible to make dartdoc link to it. I'm mostly concerned about making generating GitHub links easier as that's what lots of people use, but if we can do more that's great too.

[jcollins-g]

@isoos @jonasfj Also, you need at least 0.28.1 for source code links to start appearing in packages that have configured them. I recommend 0.28.1+2 (latest) as that includes some style changes needed for Chrome 72.

[jcollins-g]

@jonasfj

On topic: the idea that there is a button you can click which sends you to a place where you can edit code and submit a PR is pretty cool. GitHub always has this logic, you're right we just need to link to it. But in that case do you want to be sent to the revision that was published, or to the current master branch?

I was envisioning the revision that was published. If you send the link to the master from an older package version, it will seem to connect to the wrong place, and even if it happens to work for many links, it seems more correct to try to link to the exact revision.

If the user edits based on an old revision they'll have a merge conflict if something significant changed. GitHub has pretty good tools already for dealing with that, so I would suggest just letting GitHub's conflict resolution deal with any confusion.

[jonasfj]

Maybe we just need pub publish to ask for permission to include a source field in the pubspec.yaml...