jekyll: automatic edit url generation for remote resources

[crazy-max]

It's quite hard to keep track of "edit url" in our configuration for remote resources. Some of them are not there, only match the parent folder or are broken like: https://docs.docker.com/desktop/extensions-sdk/dev/cli/usage/

Here the "Edit this page" button is relative to the current repository and not the upstream one: https://github.com/docker/docker.github.io/edit/master/desktop/extensions-sdk/dev/cli/usage.md

This PR makes some changes to our fetch remote resources plugin to automatically generate edit_url for the right scope when a resource is fetched remotely. This way we don't need to maintain them in our configuration.

In a follow-up we should also look at making this kind of automation for remote docs reference like https://docs.docker.com/engine/reference/commandline/buildx_bake/.

Signed-off-by: CrazyMax crazy-max@users.noreply.github.com

[netlify]

✅ Deploy Preview for docsdocker ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	c2ee94c
🔍 Latest deploy log	https://app.netlify.com/sites/docsdocker/deploys/62a2fb21abf36c000acea7f3
😎 Deploy Preview	https://deploy-preview-14799--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[crazy-max]

Now https://deploy-preview-14799--docsdocker.netlify.app/desktop/extensions-sdk/dev/cli/usage/ has for edit url https://github.com/docker/extensions-sdk/edit/main/docs/dev/cli/usage.md

[thaJeztah]

only match the parent folder

I'd have to check the full content of this PR, but I know these can be a bit tricky;

• Some of the external content (most notably the ones using the "yamldocs") may be based on a "snapshot" / specific version in time, so content (and files) upstream may have changed on the upstream "main" / "master" branch
• However, we don't want pull requests against the upstream release-branches (instead have pull requests on "main" / "master", and backport if needed), otherwise the next release done from "main" / "master" would potentially miss the fix.
• As most repositories (outside of the docs repo) require a DCO sign-off, I know I tried to avoid using "edit" links to the upstreams, as then the user would click "edit", and edit the file through GitHub's web UI, and open a PR without DCO sign-off. Linking to the "directory" still has that risk, but "tries" to at least make the contributor have a look at the repository before opening a PR

For that last one, perhaps the edit links could point to an intermediate page ("this page is maintained in repository X. Before opening a pull request, read the contribution guidelines for that repository" (with links to both?)) - just thinking out loud here. 🤔

[crazy-max]

However, we don't want pull requests against the upstream release-branches (instead have pull requests on "main" / "master", and backport if needed), otherwise the next release done from "main" / "master" would potentially miss the fix.

Indeed it might not make sense. Maybe we could add an edit_url_ref in our fetch-remote block like:

fetch-remote:
  - repo: "https://github.com/docker/cli"
    ref: "20.10"
    edit_url_ref: "master"
    paths:

Or name it default_branch.

As most repositories (outside of the docs repo) require a DCO sign-off, I know I tried to avoid using "edit" links to the upstreams, as then the user would click "edit", and edit the file through GitHub's web UI, and open a PR without DCO sign-off. Linking to the "directory" still has that risk, but "tries" to at least make the contributor have a look at the repository before opening a PR

Yeah this one is tricky indeed. I guess that's why docs repo does not have DCO sign-off enabled? Maybe this is stupid but do you know if probot have a DCO config to exclude some paths for example?

[crazy-max]

Yeah this one is tricky indeed. I guess that's why docs repo does not have DCO sign-off enabled? Maybe this is stupid but do you know if probot have a DCO config to exclude some paths for example?

Not sure but Third-party remediation support might do the trick: https://github.com/dcoapp/app#third-party-remediation-support

[crazy-max]

@thaJeztah added default_branch field in fetch-remote config that will be used as edit url ref.

@usha-mandya issue url is now automatically generated for remote resources.

Preview: https://deploy-preview-14799--docsdocker.netlify.app/registry/spec/manifest-v2-2/

• edit url: https://github.com/distribution/distribution/edit/main/docs/spec/manifest-v2-2.md
• issue url: https://github.com/distribution/distribution/issues/new?body=File:%20[registry/spec/manifest-v2-2.md](https://docs.docker.com/registry/spec/manifest-v2-2/)

[usha-mandya]

This is great. Thanks @crazy-max.

For Docker CLI docs, the Request docs changes link still points to the Docs repo. Should we also change this to point to the upstream CLI repo?

[crazy-max]

@thaJeztah As discussed, added back the "best-effort" edit url for engine references. In a follow-up we can see how to generate edit url for references from yaml files in _data folder.

[crazy-max]

As most repositories (outside of the docs repo) require a DCO sign-off, I know I tried to avoid using "edit" links to the upstreams, as then the user would click "edit", and edit the file through GitHub's web UI, and open a PR without DCO sign-off. Linking to the "directory" still has that risk, but "tries" to at least make the contributor have a look at the repository before opening a PR

Now that we can enforce DCO in the webui, I think we can move forward with this PR: https://github.blog/changelog/2022-06-08-admins-can-require-sign-off-on-web-based-commits/

[crazy-max]

@thaJeztah Any blocker? This PR would be handy for #14948 so users would be redirected to the right page to open issues and edit the page from BuildKit repo.

[thaJeztah]

LGTM

whoops, forgot we had this one 😅