Configure mergify for repos using current/next versioning

[bmorelli25]

Summary

The vast majority of doc changes should go into next, not current (and potentially backported to current).

For repositories using the current/next versioning model, we should default the "Edit this page" link to the main/master (or next branch).

Implementation

We'll need to determine if the page exists in main/master/next first. If it does, link to that file. If it does not, fall back to the current branch.

Related

Related win: #1059

[shainaraskas]

nuance: if next =/= main/master, we likely want them authoring in main/master instead (so when they cut their next branch, the changes are there)

[cotti]

We will tackle this issue in two phases.

Phase 1:

Implement a resolver to determine the existence of a given file in certain branches - main and master being priority candidates. next should also be included, with a caveat: Individual repositories should be able to inform whether next should be excluded from this listing.

The resolver will provide HtmlWriter with the final URL to be used.

Given the large amount of pages involved, we might need to consider caching strategies. A choice could be made for HTTP HEAD requests targeting the files if running git commands prove more demanding, as we get only shallow clones.

Phase 2:

Streamline backporting using Mergify to assist in the process. A template .mergify should be provided and stakeholders for repositories that don't have Mergify already set up should be guided towards adopting it.

[bmorelli25]

Working plan:
Edit button to right version number. Work with teams to set up automation that enables cherry-picking (forward-porting).

ECS / Beats / Logstash

Documention enabling mergify when setting up current/next

@cotti to connect with @shainaraskas to ensure this fixes the problem.

[shainaraskas]

while I don't have as much invested in this strategy as @colleenmcginnis because my repos aren't using this yet, I don't think that forward-porting is the safest option. if people author in main/master, we have a much lower chance of "losing" content than if people are authoring against branches. backporting/forward-porting has historically been one of our most error-prone and hand-holdy processes (and is often skipped). if content is in main/master, it's easier to backport later and guarantees that we'll eventually get the content exposed regardless of whether someone messes up their porting.

We also instruct users to primarily author in main/master, so this is going to create two patterns for authors and reviewers (both dev and writer) to have to reason about, and will require us to try to adapt the guidelines to consider both backporting and forward-porting.

is the reason for this choice an attempt to reduce dev effort? concerned we're sacrificing authoring ergonomics

[bmorelli25]

backporting/forward-porting has historically been one of our most error-prone and hand-holdy processes (and is often skipped)

This has not been our experience on the Observability side. Backporting/cherry-picking with mergify is easy and automatic (keep me honest, @colleenmcginnis).

is the reason for this choice an attempt to reduce dev effort? concerned we're sacrificing authoring ergonomics

No. The challenges called out in our meeting this morning were around content moving or changing across versions. cc @reakaleek to add more context

[reakaleek]

I think if we really want to use the default branch for the "Edit this page" button, it needs to very obvious that you will edit a future version of a page.

Otherwise the user will encounter the following scenarios:

• The user clicks on "Edit this page" and creates a pull request, which gets eventually merged. The contributor might be surprised that the changes are not reflected in production because the assembler content source is still current (e.g. 9.0).
• The user clicks on "Edit this page" and can't find the bug in the docs (e.g. typo) he was trying fix because it is already fixed on the default branch.
• The user clicks on "Edit this page" and GitHub returns 404 because the file was moved or deleted on the default branch.

[colleenmcginnis]

This has not been our experience on the Observability side.

➕

I'm not very worried about this at the moment for beats, logstash, and ecs. Most contributions come from the engineers who aren't generally using the edit button. I wonder if we should wait and see — come back to this in a couple sprints to see if it is a problem.

[reakaleek]

Possible mergify rule:

  - name: forwardport docs changes to main
    conditions:
      - merged
      - label=docs
      - files~=^docs/ # instead of label we could use files. So mergify triggers whenever a file in the ./docs folder is changed.
      - head~=^\d+\. # not sure if this pattern actually works. But the idea is that mergify triggers on any branch that starts with a number followed by a dot.

    actions:
      backport:
        assignees:
          - "{{ author }}"
        branches:
          - main # or master
        title: "[{{ destination_branch }}](forwardport #{{ number }}) {{ title }}"

This rule would trigger for any PR with a "docs" label or changes in the docs folder in branch that is named after a version. I think using the files condition might be the safer option.

Mergify would then create a PR with the same changes to the main or master branch.

The owners of the repo can still decide if it makes sense to merge the forwardport PR.

[shainaraskas]

will defer to @colleenmcginnis on priority because none of my team's repos are affected.