Moving the Silverblue Docs to GitHub

#1

TL;DR - the source code and issue tracker related to Silverblue documentation is now at https://github.com/fedora-silverblue/silverblue-docs. Rendered documentation continues to live at https://docs.fedoraproject.org/en-US/fedora-silverblue/

After two polls asking for input on where the source code and issue tracker for the Silverblue documentation should live, the move to GitHub is underway.

The feedback about this move that came from the two threads/polls was very lively and prompted lots of great discussion. The response to this topic has been impressive and it’s encouraging to know that the community cares enough about this topic to share their different opinions.

The results of the “GitHub vs GitLab” poll were split down the middle exactly, which did not provide the necessary support for choosing one or the other by those results alone. However, the results of the first poll showed that the community did have majority support for moving to GitHub.

Unfortunately, the choice of moving to GitLab was simply not feasible given the current circumstances. There is no GitLab instance that is actively maintained by the Fedora infrastructure team and it is not clear when or if one will be deployed. The offers from community members to operate a GitLab instance for this purpose are generous, but they are not the right choice for the project.

Ultimately a decision needed to be made for this move and GitHub was chosen after evaluating the results of the polls, the feedback from active community members, and the availability/cost of a replacement service. This decision will inevitably disappoint some members of the community, but hopefully it will not be reason enough to abandon the project completely.

7 Likes
#2

Of course, other benefit would be being able to cross reference issues to rpm-ostree / flatpak / podman / etc natively!

2 Likes
#3

I cannot believe that the voice of the people was ignored as such. GitHub is a
proprietary platform, and exactly against the ideals of the Fedora project.
The poll was, as stated, split down the middle. The first poll doesn’t matter
in the least, as it did not even have the option of using GitLab.

How exactly was a move to GitLab “not feasible given the current
circumstances”? It was made clear in the second poll that the GitLab.com
instance is what was being considered, and not a Fedora-run instance, as I
suggested.

1 Like
#4

…

So it was listening to the voice of the people, just one half… One side was inevitably going to end up losing.

On a related-ish note, this reminds me of CPython’s proposal to move the bug tracker to GitHub, where Brett Cannon explained why Roundup was originally chosen:

We actually said Jira was our choice unless enough
people came forward to volunteer to help support us using Roundup. In the
end enough people did step forward and people didn't like us using Java and
a closed-source solution, so we went with Roundup (this is when RMS got
involved and asked us to reconsider; this is also when I learned that
volunteers saying they will help with something doesn't mean they actually
will, especially when they have no established reputation ;) .
2 Likes
#5

It seems like a previously adopted decision maked up as a community one. During the first poll thread we saw that the original problem was not really a problem and was fixed.

Then the second poll was about github.com vs gitlab.com but now you announce that you’re moving to github due to not knowning when a self hosted gitlab ce will be available (wtf, we were choosing between non self hosted options).

Imho it’s fine that the contributors team choose where they develop, but we didn’t need all this fake community decision circus for that.

#6

You have to consider that strong voices in this discussion came from people not even using or contributing to Silverblue. That’s one thing.

We have done a previous poll for CoreOS with these results:

results.png1095×805 25.8 KB

This was done via a Google form and shared via Fedora and CoreOS channels. You can see more information about that at https://coreos.fedoraproject.org on the main page (might have to scroll down a bit). The existing Container Linux community is not Fedora, so do not mistake the project as having the same values and missions. That said, Fedora CoreOS, the merger of Project Atomic’s Atomic Host and Container Linux, is under the Fedora Project which means it does adhere to Fedora missions and values. These missions and values are not brushed aside just by using the existing CoreOS GitHub. It is the biggest platform for open source projects, it helps people find jobs, it helps people and projects come together. Our first choice for Silverblue was also GitHub, as Silverblue is the continuation of Project Atomic’s side project Fedora Atomic Workstation, but we could not use it due to constraints within Fedora - these constraints do not exist anymore and we made the first vote without Gitlab simply because of CoreOS’ poll results.

Since several people asked for Gitlab to be included, we made the second vote which is not watered down by Pagure votes. It is a clear 50/50 on a forum that is by nature heavily against GitHub and where people who are not using Silverblue have voted, just for the sake of the project not being on GitHub. It is still a clear 50/50. Gitlab needed to be only at 51% for us to move to Gitlab. We know that the decision disappoints the 50% of Gitlab voters. With a 50/50 vote, there is not really one great outcome. See below for further reasoning.

Now, let’s say 5 vote for GitHub and 5 for Gitlab. Out of those who voted GitHub, we know the main contributors are in there and out of those 5 who voted Gitlab, we know some have expressed they’re not even interested in the project, but $principles. What are you going to go with if you want to move the project forward instead of using time and resources to fight confirmation bias?

The core contributors wanted to be on GitHub due to reasons explained in previous discussions (cross-referencing issues and commits in projects like rpm-ostree, flatpak, CoreOS, buildah, podman), more familiar and feature-rich UI, more incentive for people to contribute due to visibility).

How much time are you willing to commit to help with the project? We are definitely willing to look at options for people who do not want to use GitHub but express a clear wish and dedication to help with the project. We can look into mirroring or other, manual, ways of making clear that the contribution comes from a source outside of GitHub, including attribution. If 10 people that we know from the community who are active users tell us they are delighted about GitHub (the poll came because there were several voices expressing that before and we wanted to know what the actual distribution is rather than hearing some people and thinking that’s what everyone thinks) and one person says “I’ll never contribute to the project again”, then we’ll look into the data. We’ll also offer that person ways to contribute without using GitHub.

1 Like
#7

My biggest concern here is about the process:

  • You’re saying that a lot of people that had voted are not actual silvervlue contributors and we should take that in account. I’m fine with that, but then why did you made a public non controlled poll on the first place? You could ask to the silverblue team and announce the decision to the community.

  • The first silverblue docs poll was opened due to a specific issue, and dutong that thread we saw that the specific issue was an user issue and not an platform issue, but you continue with the process

  • The second one was about gitlab.com vs github.com and you made clear that was the hostes gitlab.com version, not a gitlab ce instance. But the first reason given to choose github is that there is no a fedora gitlab ce instance. That has no sense.

C) Now you’re talking about some underlying reasons about fedora constraints.

So that what I see from outside silverblue team: you wanted to host the project on github, and you were looking for any reason to move all the repos asap to github, but instead of saying that, you’re masking this as a community open decision when the reality is other: you were tied to pagure due to other reason, now you aren’t so you move

IMHO, The fake community decision part has no sense and had been a pantomime, add we can see that on this very thread with that initial reason without any sense and the rise of the real underlying reasons after someone pointed to the incoherent part of this process.

#8

I understand what you’re saying. As a place for checking out what the community thinks, the Fedora forums are better than Twitter and there is no other fairer way of taking big votes where many people can express their opinion - for this forum, you need a Fedora account, so it makes the most sense. We cannot make it mandatory via technology that only those people vote, who are using Silverblue. Had we wanted to not listen, we could have just moved or done a Twitter poll, as we consider those more as a snapshot of what the people on Twitter who are somehow related to the account think. We have such a poll running currently, about rolling releases. Many people have asked but it is unlikely that we will have rolling releases. It is still important to check out how many people actually want them, so we can eventually ask for it or change things when the timing is right.

Ad #1: We did ask the Silverblue team. The wide majority of the core contributors wanted GitHub (see reasoning explained above and in the previous polls), so the next step was to gauge whether the community would be ok with that. It took several discussions after the 50/50 vote to see what we’re going to do next. The decision made now is simply by “we have a split community, so whatever we do, it’s not great, but at least we can work better and have better visibility”. Some decision have to be made. What makes it right to choose Gitlab if it’s a 50/50 vote? What makes it a fake community circus to go with GitHub if it’s a 50/50 vote? Would you be posting the same things if it had been 49/51 Gitlab/GitHub? We didn’t choose a 50/50 outcome. We’d have preferred a clearer outcome either way in order to avoid discussions like this.

Ad #2: The specific issue was not resolved. If @jakfrost would like to chime in, feel free to do so. Otherwise, I’ll explain: Merge conflicts happen and not everyone needs to know all git commands in order to contribute to Silverblue. Knowing git should not be mandatory and we’re happy about contributions to the documentation and everything else. Neither should it be required to have to be on your laptop to resolve merge conflicts - both GitHub and Gitlab offer merge conflict resolution via UI which means it is fast and simple for everyone involved. So, no, the original issue was not resolved, and neither are the other bugs and lack of features (forwarded as a document to someone from the Pagure team, some of the things already exist as issues) in Pagure. Most importantly, there is a lack of resources to fix all the issues. I’d like to not derail this thread into another Pagure discussion, but no, the specific issue was not resolved after all.

Ad #3: The first post is maybe confusing about the Gitlab instance versus hosted - we did say previously that a hosted Gitlab only makes sense if there is an on-premise Gitlab in sight which there isn’t. Using hosted Gitlab we have less visibility and no cross-referencing but we have the option to easily migrate to a Fedora Gitlab if that was to happen (for which there are no plans as of today). Regardless, if the community had wanted Gitlab, we’d have gone with Gitlab, as we hope there will be more contributions which would help us improve the project faster. It does increase overhead for us, but it works.

What exactly is it that you’d like differently? We should have just moved to GitHub because it’s what the majority of us wanted from the start but couldn’t do? We should have stayed still on Pagure because the outcome was 50/50? This is about documentation and issues only, nothing else changes. These two things are the easiest ways for newcomer contributors and should be on a known platform. Gitlab is one of the two main known platforms for this. Personally, I very much like Gitlab. From a professional and project perspective, GitHub is the right choice. From a community perspective, GitHub is 50/50. I already asked you, how much time are you willing to invest in the project’s documentation? I’ll gladly work with you to get things into the documentation and have your name on the author’s list even if you never want to click on a GitHub link.

1 Like
#9

What would I like? Some coherency.

About the initial issue, well, you said that was not fixed, @jackfrost on the original issue says another thing:

About the second poll and this announcement:
You said:

The reason to move on this thread OP is:

Unfortunately, the choice of moving to GitLab was simply not feasible given the current circumstances. There is no GitLab instance that is actively maintained by the Fedora infrastructure team and it is not clear when or if one will be deployed. The offers from community members to operate a GitLab instance for this purpose are generous, but they are not the right choice for the project.

We are talking about one thing or the other?

And finally, we discover after all this that the initial intent was to move to github but you had some constraints that now don’t exist.

Sooo, what’s all this about?

#10

I see, the perceived incoherency comes from us not having written up a similar document as the Silverblue Origins one and obviously not expressing the middle steps in detail. These are things to be done for big communities as they take a considerable amount of time and doing Silverblue isn’t my main job either. I’m trying to help Silverblue grow into the big community that can ask for resources. Let’s try and get some coherency from historical context:

From the initial discussions on the Fedora Atomic Workstation SIG on IRC and over various mailing lists from atomic-devel to coreos to any others, Pagure and GitHub was always something with very diverse and very vocal opinions. We were constrained by having to use Pagure - we didn’t have the same constraints for the website which is why that one started out with GitHub while issues and documentation had to be on Pagure after we moved the docs from GH to Pagure. We could have left the documentation on GitHub where it was initially, but when we decided to have the Silverblue documentation on the official Fedora documentation as it made more sense and we were allowed to, we were told it has to be on Pagure. So we moved.

Now we can source it from GitHub after all, so we wanted to do that before the community grows bigger. There’s a whole lot of discussions on IRC with and without logs from meetings around naming for Silverblue and where things should live. So the incoherency comes from many people having many opinions. Gitlab was something some community members asked about, so we made that an option. It turned out to be 50/50. We can’t change how things happened in the past but we can get things done more coherently from now on. Shall we create a Charter and make sure that discussions in the future have a certain voting system and how would you like decisions of 50/50 to be handled? None of us are paid for Silverblue, so also keep in mind that if you don’t have the time for it, most of us likely don’t either. If someone wants to step up and take care of merging PRs, updating the website, poking about fixing issues, closing them, adhering to rules from Fedora and the other projects that are involved, we’d be quite happy. If you want to draft up a Charter, you’re most welcome as well.

#11

Hello @sanja & @jlanda,
The issue with Pagure still exists today. I originally had issues with commits, that I was doing as I was editing the guide, and those errors I introduced seemed to be a result of getting into a detached head state that I caused. The first time I came across it @miabbott helped me through the process of how to recover, this was a half day long thing, which from my POV was Okay since I had the time allotted and the flexibility to make time. This is not always the case, and @miabbott and @sanja have both been exemplary in helping me resolve both that issue and the one I have now. Lately, I was holding off on doing commits since I didn’t want to do something before the decision was made. I had one series of commits in my working local branch, with another previous commit on my master branch (local), what I did that time was push from my local master to my fork on Pagure, it looked okay. I pushed from my local working the second commit I needed to make. Both commit’s are now sitting in Pagure (and they are accurate). I do git status and they show up correct. So at this moment I make a PR for the commits but @sanja can’t merge them there are errors. So here is where it gets fun, I try to undo my last commit, to reset the head then fetch from my remote fork so I can get my local clone(s) back to the same state as the remote. This should be easy to do, but for some reason on Pagure it isn’t. So I ask @sanja if things are messed up still on her side and sure enough they are. This is the same situation I arrived at through two different approach vectors. Now maybe some of my issues are my relative (say to a developer) newness to Git, it is a fact I don’t use it daily. But git is pretty easy to use and I use it a lot more now, even still practicing with it a bit to get better at some of it’s more common commands and uses. And I doubt @miabbott is interested in spending another half day helping me through the resolution. So I can reset commits I don’t want to go ahead with on GitHub for instance, and it takes a couple of commands and I am back in business, no muss no fuss. That to me is the point of what was at the core of my issue with Pagure, and potentially others issues with it, and there is the difference, recovery ease.
So I guess from my POV I don’t like being the poster boy for getting rid of any open source project being used by this community, alternatively I also think that to get contributors, they have to be able to contribute. As for Twitter/Facebook/Pick your social media platform, sorry but I have never joined and won’t so my vote wouldn’t have been counted if they were the source.
As for an underlying reason, I am certain it comes down to the simple fact there are limited resources volunteering for Silverblue, and well most FOSS projects it seems. We’re what 98% water, so it’s no wonder we tend to take the path of least resistance.

3 Likes
#12

If half of users have a problem with the use of GitHub, a discussion must be
had to address these concerns, rather than simply ignoring it and defaulting
to the proprietary nonsense that is exactly against the Four Foundations.

#13

I agree, this is quite frustrating.

#14

This is absolutely fine, but if the core contributors had already made this
decision, polling the community and then ignoring the results of that poll is
not the answer. Nobody would have an issue if that decision had simply been
made and stuck with.

#15

Not advocating one way or the other in this discussion - it’s entirely up to the people working on Silverblue documentation!

But this type of local command line manipulation really isn’t affected by pagure vs. github at all. It’s probably just some confusion about the git model that caused an appearance of a difference. Feel free to ask for help on #silverblue or elsewhere - despite its widespread adoption, git is Not Easy - I spent my first year or two with it typing commands blindly :slight_smile:

(There could be differences in how well the system can rebase PR’s, of course, so maybe you’ve had to deal with the cli more for pagure.)

1 Like
#17

I agree, but the impression I got was my particular issue, user created or not, was more difficult to recover from (on Pagure) than say other repo hosting offers available may have tools for.

Also agree, I didn’t mean to imply I became an overnight guru, and VCS’s are not entirely foreign to me. I was referring to the ease with which I was able to do a comparable task on either platform, it may indeed be that it is only my limited understanding of the tools that is the problem. However, I did take the time to check into my issue prior to even contacting @sanja or @miabbott about it, at the Pagure issue tracking site. There was a very similar issue that had been open for a long period with no activity on it, and the complaint was from a user who was administrating, not like me contributing only, so used the cli of Pagure I would assume.

#18

I hate to clutter this thread with irrelevant detail, but do you have a link to that issue?

#19

[quote=“otaylor, post:15, topic:1203”]
But this type of local command line manipulation really isn’t affected by
pagure vs. github at all.
[/quote]

I agree, but the impression I got was my particular issue, user created or
not, was more difficult to recover from (on Pagure) than say other repo
hosting offers available may have tools for.

[quote=“otaylor, post:15, topic:1203”]
despite its widespread adoption, git is Not Easy - I spent my first year or
two with it typing commands blindly :slight_smile:
[/quote]

Also agree, I didn’t mean to imply I became an overnight guru, and VCS’s are
not entirely foreign to me. I was referring to the ease with which I was
able to do a comparable task on either platform, it may indeed be that it
is only my limited understanding of the tools that is the problem. However,
I did take the time to check into my issue prior to even contacting @sanja
or @miabbott about it, at the Pagure issue tracking site. There was a very
similar issue that had been open for a long period with no activity on it,
and the complaint was from a user who was administrating, not like me
contributing only, so used the cli of Pagure I would assume.

[Visit
Topic](https://discussion.fedoraproject.org/t/moving-the-silverblue-docs-to
-github/1203/17) or reply to this email to respond.

You are receiving this because you enabled mailing list mode.

To unsubscribe from these emails, [click
here](https://discussion.fedoraproject.org/email/unsubscribe/df9e51a8c59e40
947fd9e7e22f41ad1790cf090280e1167943a60c312e73d07d).

I was not aware that Pagure had its own CLI tools.

#20

Me neither, just followed along with what was offered by @otaylor.

#21

(drifting further from the topic.) It actually does have it’s own cli - or two - see the ‘cranc’ and ‘pag’ packages in Fedora. But those are for things like being able to open issues from the command line. I just meant using the normal git command line interface.