On Fri, Apr 30, 2021 at 6:18 PM Michal Schorm <mschorm at redhat.com> wrote: > > On Fri, Apr 30, 2021 at 11:48 AM Tomas Tomecek <ttomecek at redhat.com> wrote: > > This is where I'm stopping my replies because your language is just > > way too offensive and I am not interested in this kind of discussion. > > Right, this was a tremendously frustrating week for me and it was > wrong to pour the frustration to you too, as it helps nothing. > I'll try my best to approach it calmly. I understand - so many changes taking place it's easy to get lost and be frustrated. I'm really happy that you didn't fall for the despair fully and that you are now active in improving the workflow, documenting the process, and helping others with questions and problems - that's exactly the collaborative spirit we all should nurture. Keep on the great work! One tip which helps me personally when I feel frustrated, angry, desperate, or just tired: stand up, leave my computer, dress up and take a walk in the fresh air - works all the time for me. > On Fri, Apr 30, 2021 at 11:48 AM Tomas Tomecek <ttomecek at redhat.com> wrote: > > On Thu, Apr 29, 2021 at 5:14 PM Michal Schorm <mschorm at redhat.com> wrote: > > > The "Contributing to CentOS Stream" webpage: > > > https://wiki.centos.org/Contribute/CentOSStream > > > is very confusing (at least to me) and lacks a lot of details. > > > > It's true the documentation is not finished yet - the CentOS Stream > > team is planning to provide comprehensive contributor's documentation, > > the wiki is really just an intro. > > I'm glad to hear that ! > It's not clear to me from your sentence - the "comprehensive > contributor's documentation" will be a wiki too or some different > platform ? > Just curious; wiki is IMO fine as long as it accommodates all the needed info. Brian Stinson reached out to me that the team is already working on the documentation over here: https://github.com/CentOS/docs-contributors-guide In the coming weeks, I'd love to migrate the wiki page and all of its subpages to the docs-contributors-guide repository and just link to the rendered version: https://docs.centos.org/en-US/docs/ (tracking jira ticket: https://issues.redhat.com/browse/PACKIT-1362 ) once we start working on the migration, Michal, we'll go through your feedback in this thread and incorporate it into the guide, hope that works for you thank you again for your thorough feedback! > > > (2) > > > Section 1 > > > Text: "You should always open a bugzilla first" > > > > > > "Should" ? > > > The process *requires* package maintainers to have the ACKed BZ > > > referenced in the commit message, otherwise it will be impossible to > > > merge it. > > > I haven't heard of any other way, so this should be changed to " *MUST* ". > > > > The reason I wrote "should" there is that it may already be a bugzilla > > opened for the MR. I can see that Rich already changed it to "must" so > > let's keep it that way because that would incentivize potential > > contributors to discuss changes first, which is what we really want. > > > > > Also, the GitLab offers features such as "Issues" and so on. Will > > > those be globally disabled to discourage the contributors to file > > > tickets in the wrong place ? > > > > Yes, issues are disabled. Bugzilla is still the official tracker. > > My confusion originates from the step(s) in the workflow that wasn't > clear to me. > As I understand it *now*, the outside contributors are not supposed to > be responsible for the commits to workflow parts (getting BZ; > referencing it in the commit msg). > > If that's the case, it might be beneficial to mention that the > maintainer will have to deal with that in order for the commit to be > able to be merged; > but the "MUST" seems to be too strong. > However another sentence encouraging to discuss the issue first might > be also nice. > > > > (3) > > > Section 1 > > > Text: "As with any open source projects, in the end it's up to > > > maintainers to decide which changes they want to accept and maintain, > > > so Red Hat maintainers can decline contributions for any reason." > > > > > > This sentence is heavily suggesting that only "Red Hat maintainers" > > > have the power to decide the fate of the contributions. > > > > Correct. > > > > > Does that mean that there can be no CentOS stream maintainer that is > > > not a RH employee at the same time ? > > > If yes, why don't make this clear and say it explicitly ? > > > > I'd say it's explicitly stated there already. Please suggest a better > > wording if you have one in your mind already. > > Yes, I would love to have it stated more explicitly. > > What about: > "As with any open source projects, in the end it's up to maintainers > to decide which changes they want to accept and maintain. Since the > CentOS Stream serves as a direct upstream for the RHEL, the > maintainers of the CentOS stream are Red Hat employees and they can > decline contributions for any reason." > > I also tried to stress the likely main reason for MR decline - that it > won't fit RHEL at the end. > > > > > Also if yes, why can't I login to CentOS project using Red Hat > > > credentials or SSO ? > > > > Because the CentOS identity provider is not utilizing Red Hat's SSO - > > I'd suggest starting a new thread for such a request because that's a > > big one. Though you can log in to GitLab via https://red.ht/GitLabSSO > > I will be happy to start the thread. > But first I would like to clarify, what for ate the CentOS FAS > accounts needed, in the case of the very CentOS Stream. > > If the only benefit for the Red Hat employees would be the ability to > update some wiki pages or similar "stuff around", > It would seem perfectly OK to me that anyone who wants to do that can > get that account on their own. > > On the other hand, if there are common tasks expected to be done, > maybe even repeatedly, by Red Hat employees, which would require the > CentOS FAS account, I would want the accounts to be managed > automatically. (e.g. via RH SSO) > > No point in granting privileges to do stuff in the CentOS project to > hundreds of accounts of RH employees, when the vast majority of them > won't ever need them. > > > > (4) > > > Section 1 > > > Text: "It's also great to have it in Fedora Linux first as well." > > > > > > AFAIK, the OS you are mentioning is named "Fedora" or you can use > > > "Fedora Operating System" (to distinguish from the Fedora Project that > > > has a broader portfolio than just the OS). I think the "Fedora Linux" > > > is not correct. > > > Correct me if I'm wrong > > > > https://communityblog.fedoraproject.org/fedora-is-a-community-fedora-linux-is-our-os/ > > As already pointed out by Miro Hrončok. > Thanks for showing me. > > Would you please correct the other occurrences of the "Fedora" to > "Fedora Linux" ? > > > > > Also, shouldn't be the "It's also great to have it in ..." statement > > > which is "nice-to-have" like, rather something more stressing the fact > > > that Fedora serves as an upstream for RHEL an in order to avoid future > > > regressions, it is very important to have the change accepted in the > > > Fedora first - if possible && if it makes sense. > > > The Red Hat package maintainers have to do it (the upstreaming of > > > relevant code to Fedora) anyway as a part of their job. > > > Also, how would it need to be a part of the upstream project and not > > > to be in Fedora at the same time ? I mean Fedora (at least Rawhide) > > > aims to provide the latest upstream versions possible. > > That's why I mentioned "if possible && if it makes sense". > > > This is really hard because you have plenty of software that is being > > built and configured differently for all the distributions: kernel, > > qemu-kvm, *-release, subscription-manager... > > > > I'll reword that statement and will make it more clear. My assumption > > is there would be a dialogue between the maintainer and the > > contributor on how to handle specific contributions: I'd say it's > > perfectly reasonable to ask the contributor to propose the patch > > upstream or to Fedora Linux first. > > Right, that makes sense to me. > The fact is that the maintainers would most likely maintain the same > package in Fedora too, so they will know the best, whether it is > reasonable to ask to duplicate (or move) the request to Fedora Linux. > > > > > (5) > > > Section 2 > > > Text: "If you want to contribute to CentOS Stream, you need to have an > > > account in CentOS FAS." > > > > > > Same issue as (3), same questions I ask. > > > > > > How comes it that I do not have the account and still I can contribute ? > > > The statement is most likely false. > > > > I agree this piece is slightly outdated because the sources are now > > placed on two locations: git.centos.org and > > gitlab.com/redhat/centos-stream > > > > I'll update it. > > I've got a feeling the account might not be really needed (or even > useful?) for the contributor who contributes solely to the "CentOS > Stream". > But I might be wrong. > As I wrote regarding the SSO. > > > > > (6) > > > Section 3 > > > Text: "Once your account is set up, you can proceed to clone the > > > respective package repository locally." > > > > > > You can't clone the package repository locally without any account at all? > > > That would be weird for a public Git repos ... > > > > > > I'd reformulate the sentence such as "The next step you like to do is > > > to clone ... " > > > Also, the actual goal is not to clone the repo, but fork it, so let's > > > state that fact right away: > > > "The next step you like to do is to clone a package (project) from one > > > of the following repositories and fork it" > > > > That's a good point, I simplified the section. > > Again, it feels like that only applies to the other than "CentOS > Stream" projects. > Is that so ? > As I am continually discussing those - and many similar - subjects > around, there was a good suggestion to strongly separate information > relevant for the "CentOS Stream", just as the "CentOS Stream" itself > is strongly separated from the rest from the CentOS projects. > > > > > (8) > > > Section 3.1 > > > Text: "You'll be able to see 3 types of branches: > > > > > > Not all projects have all 3 types of the branches. > > > It would be better to say something like "The repository will contain > > > some of these types of branches:'' > > > followed by a bullet point list > > " > > To me, it already says that. Would this wording work? "Branches in the > > repositories follow this naming pattern:" > > Yeah, sound's good to me > > > > (9) > > > Section 3.1 > > > > > > Also, what about showing some instructions on how to do it? > > > Do the contributors from the general public know about the "centpkg" > > > tool or should they work with bare "git" ? > > > > I'll mention centpkg though it doesn't have comprehensive > > documentation out there yet. > > I understood at the very beginning, the new documentation is on the > way - which is great. > The whole page felt very ... bare, thin, lacking much information. > > Now I get why the details are not there - they weren't supposed to be > there in the first place! > So mention of a centpkg is a main tool would be great, but I no longer > expect any usage details on this page. > > > > There is: https://git.centos.org/rpms/systemd/tree/c8s > > > > The main problem with this wiki page is that it was written as > > contributor's docs for CentOS Stream 8 while it was hosted on > > git.centos.org and it was never fully updated for Stream 9 and gitlab, > > hence the confusion. And also as you can see, Stream 8 and Stream 9 > > dist-git repos look differently. > > Copying of the documentation of the old behaviour, and leaving it > there until something better comes around is IMO a bit unfortunate. > A simple message that the docs were copied that way and the docs > writing / shaping is still in progress would significantly lessen my > expectancy for this page to currently up-to-date bearing the info and > face we are trying to present to the world with CentOS stream. > > -- > > Most of the rest of my points are something I would expect to be moved > to the more detailed documentation. > > However I'd like to continue in the discussion together, if possible. > Your answers threw a brand new light on the state of the document and > it's expected future. > > > > -- > > Michal Schorm > Software Engineer > Core Services - Databases Team > Red Hat > > -- > > On Fri, Apr 30, 2021 at 11:48 AM Tomas Tomecek <ttomecek at redhat.com> wrote: > > > > Hi Michal, thanks for your thorough feedback! More comments inline. > > > > On Thu, Apr 29, 2021 at 5:14 PM Michal Schorm <mschorm at redhat.com> wrote: > > > > > > Hello, > > > > > > The "Contributing to CentOS Stream" webpage: > > > https://wiki.centos.org/Contribute/CentOSStream > > > is very confusing (at least to me) and lacks a lot of details. > > > > It's true the documentation is not finished yet - the CentOS Stream > > team is planning to provide comprehensive contributor's documentation, > > the wiki is really just an intro. > > > > > Here is my proposal to update / fix / enhance / clarify at least some > > > of the sections. > > > > > > -- > > > > > > (1) > > > Section 1 > > > Text: "You should always open a bugzilla first" > > > > > > The link leads to the most general selection in Bugzilla. > > > Even in the "All" category, there is no "CentOS" or "CentOS Stream" product. > > > Let's clarify that the product selected should be "Red Hat Enterprise > > > Linux *" and provide more accurate link: > > > https://bugzilla.redhat.com/enter_bug.cgi?classification=Red%20Hat > > > > Oh yeah, this is gonna be really handy! I just updated it to point to > > RHEL 8 and picked CentOS Stream as the version. > > > > > (2) > > > Section 1 > > > Text: "You should always open a bugzilla first" > > > > > > "Should" ? > > > The process *requires* package maintainers to have the ACKed BZ > > > referenced in the commit message, otherwise it will be impossible to > > > merge it. > > > I haven't heard of any other way, so this should be changed to " *MUST* ". > > > > The reason I wrote "should" there is that it may already be a bugzilla > > opened for the MR. I can see that Rich already changed it to "must" so > > let's keep it that way because that would incentivize potential > > contributors to discuss changes first, which is what we really want. > > > > > Also, the GitLab offers features such as "Issues" and so on. Will > > > those be globally disabled to discourage the contributors to file > > > tickets in the wrong place ? > > > > Yes, issues are disabled. Bugzilla is still the official tracker. > > > > > (3) > > > Section 1 > > > Text: "As with any open source projects, in the end it's up to > > > maintainers to decide which changes they want to accept and maintain, > > > so Red Hat maintainers can decline contributions for any reason." > > > > > > This sentence is heavily suggesting that only "Red Hat maintainers" > > > have the power to decide the fate of the contributions. > > > > Correct. > > > > > Does that mean that there can be no CentOS stream maintainer that is > > > not a RH employee at the same time ? > > > If yes, why don't make this clear and say it explicitly ? > > > > I'd say it's explicitly stated there already. Please suggest a better > > wording if you have one in your mind already. > > > > > Also if yes, why can't I login to CentOS project using Red Hat > > > credentials or SSO ? > > > > Because the CentOS identity provider is not utilizing Red Hat's SSO - > > I'd suggest starting a new thread for such a request because that's a > > big one. Though you can log in to GitLab via https://red.ht/GitLabSSO > > > > > If not, the sentence doesn't make much sense. > > > > > > (4) > > > Section 1 > > > Text: "It's also great to have it in Fedora Linux first as well." > > > > > > AFAIK, the OS you are mentioning is named "Fedora" or you can use > > > "Fedora Operating System" (to distinguish from the Fedora Project that > > > has a broader portfolio than just the OS). I think the "Fedora Linux" > > > is not correct. > > > Correct me if I'm wrong > > > > https://communityblog.fedoraproject.org/fedora-is-a-community-fedora-linux-is-our-os/ > > > > > Also, shouldn't be the "It's also great to have it in ..." statement > > > which is "nice-to-have" like, rather something more stressing the fact > > > that Fedora serves as an upstream for RHEL an in order to avoid future > > > regressions, it is very important to have the change accepted in the > > > Fedora first - if possible && if it makes sense. > > > The Red Hat package maintainers have to do it (the upstreaming of > > > relevant code to Fedora) anyway as a part of their job. > > > Also, how would it need to be a part of the upstream project and not > > > to be in Fedora at the same time ? I mean Fedora (at least Rawhide) > > > aims to provide the latest upstream versions possible. > > > > This is really hard because you have plenty of software that is being > > built and configured differently for all the distributions: kernel, > > qemu-kvm, *-release, subscription-manager... > > > > I'll reword that statement and will make it more clear. My assumption > > is there would be a dialogue between the maintainer and the > > contributor on how to handle specific contributions: I'd say it's > > perfectly reasonable to ask the contributor to propose the patch > > upstream or to Fedora Linux first. > > > > > (5) > > > Section 2 > > > Text: "If you want to contribute to CentOS Stream, you need to have an > > > account in CentOS FAS." > > > > > > Same issue as (3), same questions I ask. > > > > > > How comes it that I do not have the account and still I can contribute ? > > > The statement is most likely false. > > > > I agree this piece is slightly outdated because the sources are now > > placed on two locations: git.centos.org and > > gitlab.com/redhat/centos-stream > > > > I'll update it. > > > > > (6) > > > Section 3 > > > Text: "Once your account is set up, you can proceed to clone the > > > respective package repository locally." > > > > > > You can't clone the package repository locally without any account at all? > > > That would be weird for a public Git repos ... > > > > > > I'd reformulate the sentence such as "The next step you like to do is > > > to clone ... " > > > Also, the actual goal is not to clone the repo, but fork it, so let's > > > state that fact right away: > > > "The next step you like to do is to clone a package (project) from one > > > of the following repositories and fork it" > > > > That's a good point, I simplified the section. > > > > > (7) > > > Section 3 > > > Text: "The package repositories are right now located in two places:" > > > > > > Two places, but four list items? :) > > > > will update > > > > > (8) > > > Section 3.1 > > > Text: "You'll be able to see 3 types of branches: > > > > > > Not all projects have all 3 types of the branches. > > > It would be better to say something like "The repository will contain > > > some of these types of branches:'' > > > followed by a bullet point list > > " > > To me, it already says that. Would this wording work? "Branches in the > > repositories follow this naming pattern:" > > > > > (9) > > > Section 3.1 > > > > > > Also, what about showing some instructions on how to do it? > > > Do the contributors from the general public know about the "centpkg" > > > tool or should they work with bare "git" ? > > > > I'll mention centpkg though it doesn't have comprehensive > > documentation out there yet. > > > > > If they should know (or even are encouraged to use) "centpkg", provide > > > the damn instructions. > > > > I don't think such language is necessary. > > > > > Otherwise, describe if the forking in the web UI is the only way and > > > how to do it. > > > > > > (10) > > > Section 4.1 > > > > > > I bet this is a confusing section, at least for new contributors. > > > > > > 1/ Let's begin with the fact that you need the fork in the first place. > > > 2/ Inside of the fork, you should create a new branch - based on the > > > branch they want to contribute to, ideally (but necessarily? ... we > > > might make a "best practice" though) named "bz12345" referencing the > > > submitted BZ ticket for easy recognition > > > 3/ commit the changes. > > > note: each commit must contain an ACKed BZ ticket in order to be > > > able to be merged to the target branch. > > > note: there will be different ACK requirements for different > > > branches in the future (e.g. Y-stream v s Z-stream) > > > 4/ Push the branch to your fork > > > 5/ create MR > > > note: when using "centpkg" as I asked above, the MR URL will be > > > created during the push > > > > > > (11) > > > Section 4.2 > > > Text: "you need to execute %prep phase to see it." > > > > > > To "see it"? More like to "retrieve it from the cache". > > > > > > (12) > > > Section 4.4 > > > > > > What the hell is this about? > > > We should be talking about a dist-git layout & workflow in this > > > section, not a RPMbuild layout (which is completely irrelevant here). > > > There are no "SOURCES" and "SPECS" directories in dist-git. that is > > > completely wrong, the whole section. > > > > There is: https://git.centos.org/rpms/systemd/tree/c8s > > > > The main problem with this wiki page is that it was written as > > contributor's docs for CentOS Stream 8 while it was hosted on > > git.centos.org and it was never fully updated for Stream 9 and gitlab, > > hence the confusion. And also as you can see, Stream 8 and Stream 9 > > dist-git repos look differently. > > > > This is where I'm stopping my replies because your language is just > > way too offensive and I am not interested in this kind of discussion. > > > > > 1/ If you want to make just a packaging change, you *likely* only need > > > to modify just the SPECfile. > > > 2/ If you want to make justa patch change, you need to add the patch > > > AND modify the SPECfile too. > > > > > > At the end, you add all the modified files, commit them, add the BZ > > > ticket to the commit message and create MR. > > > > > > (13) > > > Section 4.5 > > > Text: "4.5. After a pull request is created" > > > > > > For a reason I don't know, some people call it "pull requests" (e.g. > > > in Fedora), some people "merge requests" (e.g. in GitLab). > > > Anyway, we are working with GitLab, so use it's naming. > > > > > > So: "4.5. After a merge request is created" > > > > > > Please find all 3 occurrences of the word "pull" on the page and fix them. > > > > > > (14) > > > Section 4.5 > > > Text: "When you submit a pull request for source-git, automation will > > > pick up the change and build it " > > > > > > Does it not work for the dist-git too? > > > Why ? > > > What about mentioning the scratch-build then? ... aww hell, we are > > > back to the "centpkg" again :) > > > > > > (15) > > > Section 4.5 > > > Text: "Once your change is accepted, it will be marked with the label > > > "accepted". Our automation will create a corresponding bugzilla with > > > the patch attached and then it’s up to the RHEL maintainer to pick it > > > up, commit and build internally so that it can land back into CentOS > > > Stream" > > > > > > This is most confusing. > > > > > > Why won't a maintainer merge it into CentOS first? > > > Why would he first apply it in the most downstream place? What about > > > the "upstream first" rule? > > > > > > How can a package maintainer mark the MR as "accepted"? > > > I haven't found such an option anywhere. > > > > > > "Our automation will create a corresponding bugzilla with the patch attached" > > > So ... another BZ ? This time to ... what product ? > > > Again see (1). > > > > > > I personally actually created a MR, but none BZ has been created: > > > https://gitlab.com/redhat/centos-stream/rpms/mariadb-connector-c/-/merge_requests/1 > > > > > > "RHEL maintainer to pick it up, commit and build internally so that it > > > can land back into CentOS Stream" > > > That sentence suggests that the RHEL is the upstream for CentOS > > > stream, but at the same time we are pushing CentOS stream to be > > > upstream for RHEL. > > > Get this straight. > > > > > > BTW on a webpage: > > > https://wiki.centos.org/Contribute#CentOS_Stream > > > the re is a clear statement: > > > "CentOS Stream is a continuously delivered distribution which is > > > upstream to the next minor version of Red Hat Enterprise Linux" > > > > > > (16) > > > Section 5 > > > Text: "it needs to be reviewed and approved by the RHEL maintainer for > > > the particular component." > > > > > > Again - so only RH employees will be able to maintain ? > > > Why don't have a CentOS FAS access already created ? > > > Why would anyone else need a CentOS FAS ? > > > > > > "maintainer for the particular component" > > > Also, I believe this is a false statement too. > > > The current permissions AFAIK allow for any RH employee with the > > > GitLab account with the "devel" role over gitlab.com/redhat space to > > > merge the MR. > > > > > > (17) > > > Section 5 > > > Text: "We are making sure behind the scenes they see your patch." > > > > > > Who is making sure? > > > the RH employees ? > > > Who are "they" > > > *the same* RH employees ? :D > > > > > > (18) > > > Section 6 > > > > > > Might help to add instructions on how to do it. > > > > > > (101) > > > > > > Is there not a single documentarist as a part of the CentOS project > > > who would read through the webpages ? > > > > > > > > > -- > > > > > > Michal Schorm > > > Software Engineer > > > Core Services - Databases Team > > > Red Hat > > > > > > -- > > > > > >