Hi all,
Three months ago[1]. we briefly discussed changing the default git branch for the council-docs repo. I went ahead and made the change:
https://pagure.io/Fedora-Council/council-docs/pull-request/93
https://pagure.io/fedora-docs/docs-fp-o/pull-request/151
This took about 15 minutes with `grep` and `awk`. Ben already ACK'd the PRs and plans to merge early next week.
Sharing as a F.Y.I. if you work on Council docs soon and you have already cloned the repo. You will need to do a one-time git branch update to change from `master` to `main` once the above PRs are merged:
``` cd /path/to/council-docs/ git checkout main
# check first for local changes not yet pushed upstream git branch -D master ```
=== [1] https://pagure.io/Fedora-Council/council-docs/issue/86 ===
Three months ago[1]. we briefly discussed changing the default git branch for the council-docs repo. I went ahead and made the change:
+1 to going ahead and doing things :)
Pull requests merged. However, Pagure isn't applying the change to the default branch. Be careful where you push until I get that sorted out.
Lesson to reviewers: always run a local build. (You'd think I'd have learned this by now, but no...)
TL;DR: I've reverted the change to docs.fp.o because it breaks things in ways I can't fix. The default branch on council-docs remains 'main' because there aren't that many commits, so we can just be careful until we get this fixed.
NTL;MR (Not too long; maybe read): Apparently antora doesn't want to build *only* the 'main' branch and put it in the normal place. Instead of being in '/en-US/council/', it was in '/en-US/council/main'. I tried both using 'HEAD' and '[main, '!master']' to make it work and neither one did. The docs suggest it works, but I'm not sure the docs are thinking about having different default branches. The easiest approach may be to not set 'branches:' site-wide and instead have each repo explicitly set its branches. That's a relatively trivial change, but it's obnoxious. So for the time being, I've reverted Justin's change, which definitely should have worked. Adam is on PTO this week and he's our Antora expert, so when he's back, we can try to come up with a better solution. In the meantime, I'm not going to un-do the commit to Council-docs or change the default branch because we don't commit there often enough to make it worthwhile.
Update: "master" is a reserved word in Antora and is currently the only way to produce "unversioned" URLs[1]. While there are ways we can work around this (e.g. by creating redirects for old URLs to start using "main/"), this has drawbacks: it requires creating those redirects (which is low, but non-zero effort and requires more as other teams move to using "main" as the default repo) and it would result in local builds not working the way production builds do (i.e links may appear broken in local builds when they're not in the production version).
Given that the term "master" is relatively unexposed in our documentation anyway, I propose we put this on hold for now. I'll file an issue upstream to ask for a way to implement the desired behavior and once that is available, we can move forward. Changing non-Antora repos to use main as the default branch can still proceed where tooling supports it.
[1] https://docs.antora.org/antora/2.3/component-with-no-version/
On Mon, Nov 23, 2020 at 12:32:49PM -0500, Ben Cotton wrote:
Given that the term "master" is relatively unexposed in our documentation anyway, I propose we put this on hold for now. I'll file an issue upstream to ask for a way to implement the desired behavior and once that is available, we can move forward. Changing non-Antora repos to use main as the default branch can still proceed where tooling supports it.
+1
On 11/23/20 1:18 PM, Matthew Miller wrote:
On Mon, Nov 23, 2020 at 12:32:49PM -0500, Ben Cotton wrote:
Given that the term "master" is relatively unexposed in our documentation anyway, I propose we put this on hold for now. I'll file an issue upstream to ask for a way to implement the desired behavior and once that is available, we can move forward. Changing non-Antora repos to use main as the default branch can still proceed where tooling supports it.
+1
+1.
Please share the link to the upstream ticket once you file. I'll subscribe too to stay in the loop.
On Mon, Nov 23, 2020 at 2:12 PM Justin W. Flory foss@jwf.io wrote:
Please share the link to the upstream ticket once you file. I'll subscribe too to stay in the loop.
https://gitlab.com/antora/antora/-/issues/712
On Mon, 23 Nov 2020 at 20:14, Ben Cotton bcotton@redhat.com wrote:
On Mon, Nov 23, 2020 at 2:12 PM Justin W. Flory foss@jwf.io wrote:
Please share the link to the upstream ticket once you file. I'll subscribe too to stay in the loop.
So, we talked about this with Ben, and I realised I lied about Antora caring about the branch name. It only cares about the "version" field in the antora.yml (the config in all repos, like [0]). I went ahead and tested it, it worked, so I wanted to report results here, but I see the ticket above already has this as an answer.
So as a step 1, we can move repos to the "main" branch, and the only thing we need to change is the main site.yml [1]. We need to add a branch explicitly to those repos. This solves the git branches.
And as step 2, when they implement the empty version (see the ticket above), we can also change the individual antora.yml files in all repos to get rid of the word "master" on the site.
[0] https://pagure.io/fedora-magazine/blob/master/f/antora.yml#_9 [1] https://pagure.io/fedora-docs/docs-fp-o/blob/prod/f/site.yml
-- Ben Cotton He / Him / His Senior Program Manager, Fedora & CentOS Stream Red Hat TZ=America/Indiana/Indianapolis _______________________________________________ council-discuss mailing list -- council-discuss@lists.fedoraproject.org To unsubscribe send an email to council-discuss-leave@lists.fedoraproject.org Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/council-discuss@lists.fedorapr...
On Tue, Nov 24, 2020 at 6:39 AM Adam Samalik asamalik@redhat.com wrote:
So, we talked about this with Ben, and I realised I lied about Antora caring about the branch name. It only cares about the "version" field in the antora.yml (the config in all repos, like [0]). I went ahead and tested it, it worked, so I wanted to report results here, but I see the ticket above already has this as an answer.
So as a step 1, we can move repos to the "main" branch, and the only thing we need to change is the main site.yml [1]. We need to add a branch explicitly to those repos. This solves the git branches.
And as step 2, when they implement the empty version (see the ticket above), we can also change the individual antora.yml files in all repos to get rid of the word "master" on the site.
This makes sense, I am sad that I combined them into a single issue. I'll make the step 1 changes again on Monday.
council-discuss@lists.fedoraproject.org
-
Adam Samalik -
Ben Cotton -
Justin W. Flory -
Matthew Miller