Running make gh-pages locally deletes copies of previous submissions

[CxRes]

Let me start by saying, it is unclear to me how the template works, so this might not be coherent.

I have added a new branch intro-example to a spec https://github.com/CxRes/prep. Now the Github actions did not update to include this branch. I am not sure what triggers the action.

Next, I tried to manually update gh-pages locally by running make gh-pages locally on the intro-example branch. This deletes the 'draft-gupta-httpbis-per-resource-events-00' from the gh-pages branch presumably because it is not a branch but a tag, even though it was automatically generated at the time of submission of that draft (without a corresponding branch being generated in the repo) and still exist on the homepage. The console output is shown below

 git -C /tmp/ghpages8174 -c user.name="ID Bot" -c user.email="idbot@example.com" commit -m "Script updating gh-pages from 5af8a6d. [ci skip]"; fi
[gh-pages 360c2b2] Script updating gh-pages from 5af8a6d. [ci skip]
 4 files changed, 569 insertions(+), 335 deletions(-)
 rename {draft-gupta-httpbis-per-resource-events-00 => intro-example}/draft-gupta-httpbis-per-resource-events.html (85%)
 rename {draft-gupta-httpbis-per-resource-events-00 => intro-example}/draft-gupta-httpbis-per-resource-events.txt (83%)
 rename {draft-gupta-httpbis-per-resource-events-00 => intro-example}/index.html (83%)

Instead the locally generated gh-pages homepage now contains intro-example branch only (other than main of course). This seems wrong and I am reluctant to push this version to GitHub! A submitted draft should not just be deleted, not before it expires at least. Is this a bug?

[martinthomson]

The gh-pages stuff is definitely the most complicated part of the system!

This is all designed around the GitHub flow, where branches are generally temporarily created in order to drive pull requests. For local branches, the gh-pages target (including the CI action) creates a folder that contains a preview of the content.

However, if there are a lot of branches in flight, there is a cleanup process. Any branch that has not been updated in the past $(GHPAGES_BRANCH_TTL) days will be removed. The default is 30 days.

So, given that the branch no longer exists, the cleanup is run when the files are more than 30 days old. Then, your new branch is created. Because of the similarities, git is marking the removal and addition as a rename (though git doesn't really have any innate concept of a rename, that's just a UX thing).

There is also a cleanup process that trims the history of the gh-pages branch. This is not what you are seeing, but it can come into effect.

You can control this behaviour by setting larger values for GHPAGES_COMMIT_TTL and GHPAGES_BRANCH_TTL. A value of a billion days should ensure that you don't get bothered by this feature if you prefer to keep things forever. The drawback there is that you could end up with a very heavy gh-pages branch. We introduced these features when we were working on QUIC. We found that the repository got very large as a result of lots of commits to the gh-pages branch.

By the way, naming a branch draft-gupta-httpbis-per-resource-events-00 is probably unwise if you intend to also use tags. This "might" work, but it creates name confusion between the branch and any tag.

[CxRes]

But I have not created a branch draft-gupta-httpbis-per-resource-events-00? This (creating the corresponding folder in gh-pages) is something the I-D template did on its own when I tagged the main branch for submission. I could presumably get rid of it but keeping snapshots of datatracker submissions seems like a good idea. I definitely want branches to be deleted from gh-pages once I am done with them. What config might help me achieve that while avoiding the namespace confusion?

[martinthomson]

I have not created a branch draft-gupta-httpbis-per-resource-events-00

Strange. I don't recall building something that put something on gh-pages from a tag.

I definitely want branches to be deleted from gh-pages once I am done with them. What config might help me achieve that while avoiding the namespace confusion?

That should happen without your intervention after 30 days (though it will only happen when there is activity on the repository that causes builds to run, so it might be later than that).