Badges docs: Merging GitLab Wiki to Fedora Docs?

Continuing the discussion from Summary of April 2023 Fedora Badges Community Round-table Meeting:

We were having a lively discussion over in the April discussion thread, so I thought I’d fork it out into a new, dedicated topic.

Honestly there is not a huge amount of content in our docs site already. So, I’d think to keep what is there and merge the GitLab Wiki content into the docs site. The charters are big ones that we want to put out front and center.

I think the pre-requisite for this is getting what is in Pagure over into GitLab. I created a barebones GitLab repo (and have some local commits ready), although I don’t have permissions to edit the repo nor commit to it.

Honestly there is not a huge amount of content in our docs site
already. So, I’d think to keep what is there and merge the GitLab
Wiki content into the docs site. The charters are big ones that we
want to put out front and center.

I had to read that at least twice, but I think I understand and agree.

I think the pre-requisite for this is getting what is in Pagure over
into GitLab. I created a barebones GitLab repo (and have some local
commits ready), although I don’t have permissions to edit the repo
nor commit to it.

If you do not have commit access, how did you manage to make an initial
commit? Is that part of creating a bare repo?

I’m all for moving the Pagure docs repo over to Gitlab. Say I have
commit access and push what’s there into GitLab, will that preserve all
the commit history? I think it should, but I’m not sure.

So, not too long after posting this, @darknao was able to elevate my permissions in the Badges sub-team. Now I have admin rights on the documentation repo, so I was able to initiate a new branch.

I also learned something else talking with the Websites & Apps team. The Badges docs were already in GitLab, and for a long time now too. But they were grouped into the larger Websites & Apps docs repo. There are no docs in Pagure anymore, only fragments of the development scripts used to run the local environment.

So, the actual question now is, whether we would want to move the Badges docs to a dedicated repo of their own under the Badges sub-team. I’m in favor of a dedicated repo because I think it will make the Badges docs more visible to the folks working on Badges often and hopefully encourage us to keep them in our workflow as we press forward.

I also learned something else talking with the Websites & Apps team.
The Badges docs were already in GitLab, and for a long time now too.
But they were grouped into the larger Websites & Apps docs repo.
There are no docs in Pagure anymore, only fragments of the
development scripts used to run the local environment.

Are you sure? I can still browse the files over on Pagure[1].

I searched for Badges documentation on GitLab and found a repo[2]. It
appears to be a copy of the Pagure repo, but it does not contain
any history. There’s only one commit[3].

So, what kind of black magic is going on behind the scenes? And why do
we need to learn this bumping into it?

Right now it looks like one can still commit to the repo on Pagure. I
admit it’s a bit stale and it doesn’t happen very often. But say I do,
will there be some magic sync to GitLab behind the scenes to make the
changes available on the website?

So, the actual question now is, whether we would want to move the
Badges docs to a dedicated repo of their own under the Badges
sub-team. I’m in favor of a dedicated repo because I think it will
make the Badges docs more visible to the folks working on Badges
often and hopefully encourage us to keep them in our workflow as we
press forward.

:+1: I’m for moving the Badges docs into its own repo housed inside the
Badges subgroup of Websites & Apps. It also keeps documentation on the
radar of Badges folks.

But, I’d like to see a re-import that preserves the history. History
gives context to changes. That’s even more important for the repo that
has all the badges in it.

If there’s no tool/script yet for moving repos from Pagure to GitLab
properly, I can dig into it. I might be mistaken, but my gut feeling is
that it shouldn’t be all that hard.


  1. Overview - fedora-badges/docs - Pagure.io ↩︎

  2. Files · main · fedora / Fedora Websites and Apps / Documentation · GitLab ↩︎

  3. https://gitlab.com/fedora/websites-apps/documentation/-/commits/main/modules/badges ↩︎

Wow. You’re right, and as I dug into this, I realized that the Fedora Docs builder is building from that Pagure repo. So, this was the source of truth.

What I didn’t anticipate was that there were three repositories all purporting to be the Fedora Badges docs. I spent some time this afternoon making some changes to work towards unification:

  1. 📝 🔧 Add AsciiDoc source and Antora configs (!1) · Merge requests · fedora / Fedora Websites and Apps / Fedora Badges / Badges Docs · GitLab
  2. 💥 Remove Badges documentation (!2) · Merge requests · fedora / Fedora Websites and Apps / Documentation · GitLab
  3. PR#907: Remove remnants of Fedora Badges docs and point to the new home - fedora-badges - Pagure.io
  4. https://pagure.io/fedora-badges/docs/pull-request/7
  5. 🚚 site.yml: Change git URI for Fedora Badges docs (!8) · Merge requests · fedora / Fedora Docs / Docs Website / Fedora Docs Website · GitLab

Do you think it is worthwhile to preserve that history? It is not out of the question that we could use the Pagure docs repo as a base. It’s funny since I was the one who created that repo, but I forgot it was there. I used the content from the Websites & Apps team docs repo as the base in the new repo.

And then I kept reading, and that is what you suggested. So, I could backtrack on some of these MRs/PRs above so that the final resting home of our docs uses the same git history as the Pagure repo.

Thoughts?

Preserving the history is as simple as

  1. Create bare repo (project) on GitLab
  2. Add the new repo as a remote to an existing clone
  3. Push to the new remote

I used the following settings:

:tada: All the history is preserved:

https://gitlab.com/penguinpee/fedora-badges-docs

I added @jflory7 and @t0xic0der as developers to the project, so you can look around, but kept it private otherwise to not cause more confusion. If anyone else wants to take a look, ping me.

2 Likes