18:30:03 <bcotton> #startmeeting docs
18:30:03 <zodbot> Meeting started Wed Aug 24 18:30:03 2022 UTC.
18:30:03 <zodbot> This meeting is logged and archived in a public location.
18:30:03 <zodbot> The chair is bcotton. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
18:30:03 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
18:30:03 <zodbot> The meeting name has been set to 'docs'
18:30:14 <bcotton> #topic Roll call
18:30:21 <pboy> .hi
18:30:22 <zodbot> pboy: pboy 'Peter Boy' <pboy@uni-bremen.de>
18:30:25 <bcotton> #chair pboy darknao pbokoc
18:30:25 <zodbot> Current chairs: bcotton darknao pbokoc pboy
18:30:40 <py0xc3[m]> .hello py0xc3
18:30:41 <zodbot> py0xc3[m]: py0xc3 'Christopher Klooz' <py0xc3@my.mail.de>
18:30:42 <darknao> .hi
18:30:47 <zodbot> darknao: darknao 'Francois Andrieu' <darknao@drkn.ninja>
18:31:50 <AnushkaJain[m]1> Hi
18:31:50 <bcotton> welcome everyone
18:32:06 <py0xc3[m]> Hi
18:32:39 <pboy> zodbot needs .hi to get included in the participants list
18:33:06 <AnushkaJain[m]1> .hi
18:33:07 <zodbot> AnushkaJain[m]1: Sorry, but user 'AnushkaJain [m] 1' does not exist
18:33:19 <py0xc3[m]> If you use Matrix you need .hello
18:33:29 <py0xc3[m]> ;)
18:33:33 <AnushkaJain[m]1> .hello
18:33:33 <zodbot> AnushkaJain[m]1: (hello <an alias, 1 argument>) -- Alias for "hellomynameis $1".
18:33:43 <bcotton> #topic Announcements
18:34:00 <bcotton> #info Some F36 release notes still need to be written https://pagure.io/fedora-docs/release-notes/roadmap/F36
18:34:16 <py0xc3[m]> Anushka Jain:  say: .hello <username>
18:34:22 <bcotton> #info The F37 Beta freeze has begun. Expect to see some Changes deferred to F38
18:34:50 <bcotton> #info We use GitLab to track work: https://gitlab.com/groups/fedora/docs/-/boards
18:34:54 <AnushkaJain[m]1> .hello likeanushkaa
18:34:55 <zodbot> AnushkaJain[m]1: likeanushkaa 'Anushka Jain' <anushkajain2902@gmail.com>
18:35:00 <bcotton> Any other announcements?
18:36:03 <bcotton> #topic Review action items
18:36:19 <bcotton> #info pboy and py0xc3 to prepare a proposal to integrate the new docs into the team pages.
18:36:34 <pboy> Done
18:36:40 <py0xc3[m]> pboy and I have drafted it today: https://gitlab.com/fedora/docs/community-tools/documentation-contributors-guide/-/blob/stg/modules/ROOT/nav.adoc
18:37:21 <py0xc3[m]> Some comments in https://gitlab.com/fedora/docs/community-tools/documentation-contributors-guide/-/merge_requests/4
18:37:38 <bcotton> #link https://gitlab.com/fedora/docs/community-tools/documentation-contributors-guide/-/merge_requests/4
18:38:00 <bcotton> this leads us into the next topic...
18:38:16 <bcotton> #topic Conflict between MR/"stg" branch and "main" branch in Docs repo
18:38:25 <bcotton> #link https://discussion.fedoraproject.org/t/conflict-between-mr-stg-branch-and-main-branch-in-docs-repo/41640
18:38:43 <py0xc3[m]> We have to prepare our workflow somehow to avoid this. The more contribution and contributors we get, the more often this will happen and conflicts can sometimes cause a lot of work.
18:39:04 <py0xc3[m]> There is a comment with a summary within the MR page
18:39:19 <darknao> my opinion is you can't avoid dealing with merge conflict, that part of the git workflow
18:39:35 <darknao> especially when you keep MR open for a long time
18:39:58 <py0xc3[m]> Well, checking MR before making a direct commit could avoid already much.
18:40:14 <py0xc3[m]> In such a case a commit can be made simply into the MR
18:40:34 <py0xc3[m]> Just as one possibility
18:41:00 <darknao> that what rebase is for, to take everything from the main branch into your MR
18:41:23 <py0xc3[m]> Rebase does not work if there is a conflict ;)
18:41:52 <py0xc3[m]> I don't talk about rebasing. I agree that this is absolutely fine. And there can be direct commits. The problem is causing conflicts that make rebasing impossible.
18:42:20 <darknao> rebase will require you do fix conflicts, but a merge commit will need that too
18:42:21 <pboy> Well, my approach now would be to create a new MR for main from the contributions in STG. A simple merge is not enough in most cases anyway, but it requires rework.
18:42:25 * py0xc3[m] uploaded an image: (10KiB) < https://libera.ems.host/_matrix/media/r0/download/fedora.im/0269308947caf55932e16abfaccf2a267683b015/rebase-failed.png >
18:42:56 <py0xc3[m]> pboy: The MR is already from stg to main
18:43:30 <pboy> Don't know, whether that is a good idea.
18:43:37 <pboy> It's fine for programming
18:43:47 <pboy> But texts used to be a bit different.
18:44:19 <py0xc3[m]> pboy: I think this is part of the problem. We work more often at the same time in the same files.
18:45:04 <pboy> Yeah, that's one source of trouble.
18:45:23 <py0xc3[m]> E.g., the issue could have been solved by adding commits that affect files which are changed in the MR to the MR instead of to "main" directly
18:45:37 <pboy> The other may be, we want only parts of the changes into main.
18:46:01 <py0xc3[m]> Or making smaller and thus faster MR
18:46:52 <pboy> That 'faster' may be a problem when discussing complex texts and finetuning wording.
18:46:53 <py0xc3[m]> but we have already more conflicts in one other MR. So its not the first time. We have to be faster in processing what externals suggest. Doesn't motivate them if we let their MR open and then close them because of conflicts
18:47:29 <darknao> there is no reason to close a MR just because of conflicts
18:47:34 <py0xc3[m]> pboy: Indeed. Or initially make this in comments in tickets or MR?
18:47:38 <darknao> we can fix these easily
18:48:04 <py0xc3[m]> darknao: No. normally not. But at some points solving conflicts after several months can be more work than doing it again. People will only see that their MR is closed, not that we did it somewhere else again
18:48:24 <pboy> Yeah, or we all merge into stg, and to bring that to main and into the public is for someone, to whom we dedicate the task.
18:48:31 <py0xc3[m]> Is there some automated way if rebase does no longer work?
18:48:37 <darknao> either the contributor can do it, if they're willing to, or we can do that for them
18:49:04 <darknao> we can always do that in the same MR
18:49:09 <darknao> gitlab allows that
18:49:19 <py0xc3[m]> darknao: is there an easy+fast way? e.g., in this case?
18:49:37 <darknao> and you can always rebase, you just need to solve conflict manually
18:49:43 <py0xc3[m]> I would do it manually, each step, if rebase fails.
18:49:45 <darknao> gitlab have a mini how-to for that
18:50:05 <py0xc3[m]> darknao: That's my point :)
18:50:38 <py0xc3[m]> darknao: do you know the link?
18:51:17 <py0xc3[m]> I just know the manual way, which is vulnerable and takes increasingly time the deeper conflicts are
18:51:17 <darknao> there is no direct link, but you can find it by clicking on [Code] -> Checkout code in any MR
18:51:31 <pboy> Nevertheless, the question is, how we use stg. I think, it is a view into the future and the planning, and we will make only part of it public, i.e. add it do main.
18:52:10 <py0xc3[m]> pboy: Your idea of merging external contributions quickly into stg sounded good
18:52:21 <py0xc3[m]> darknao: Thanks! I'll check that
18:52:24 <pboy> Of what we discussed today, I think we can only make 2-3 itmes public, the rest shuóuld stay in stg for further development and work upon.
18:53:45 <pboy> And maybe one of us takes over the task to make those items public we agree upon.
18:54:34 <pboy> And stg is semi-public all the time. Es externals get their work worshiped
18:54:48 <py0xc3[m]> GitLab does not support doing this in the interface. We have to do this in command line of git: https://gitlab.com/help/user/project/merge_requests/conflicts#resolve-conflicts-from-the-command-line
18:55:21 <darknao> py0xc3[m]: well, actually, you can do it on the webui
18:55:23 <py0xc3[m]> That's the forwarding of the code > checkout in the MR
18:56:08 <darknao> but that's not compatible with the fast-forward merge type we enforce
18:56:20 <pboy> I think,  CLI is OK, at least for me. If I had to do it, I would check it out and work on it locally anyway.
18:56:40 <darknao> we can switch to the more classical merge commit, you'll still need to resolve conflict, but that can be done on the webui this time
18:56:59 <darknao> and will make much harder for us to cherry-pick commit from one branch to another
18:57:15 <py0xc3[m]> Ok. I would be fine with both. Maybe it makes sense that everyone can check out both possibilities on themselves and postpone a decision?
18:57:36 <py0xc3[m]> Ok, cherry picks would be important I think.
18:58:14 <py0xc3[m]> So two technical possibilities, or alternatively a social one with shifting the task to contributors
18:58:59 <darknao> to me, that should be us to do the rebase once the MR is ready to be merged
18:59:08 <py0xc3[m]> Well, I'm open to everything. Just would like to avoid to waste increasing time for solving conflicts. The more people contribute, the more often this will happen, and the more complex it becomes.
18:59:23 <py0xc3[m]> darknao: This is how the workflow intends it at the moment.
18:59:25 <darknao> contributors can do it too, but only if they are willing to and are confortable enough with manual rebase
18:59:36 <py0xc3[m]> But the automated rebase is one thing, solving manually conflicts the other.
19:00:08 <py0xc3[m]> darknao: I guess this is unlikely :) The 7 steps already exclude any branches as these created confusion
19:00:43 <py0xc3[m]> I think checking in advance to avoid conflicts (I'm not talking about rebasing) saves more time than doing it later, at least in the interface we currently use
19:01:07 <pboy> Hm, mayve I'm too conservative. At least in an early stage of a text, as the teampage now, I would prefer to merge to stg and determin an editor, who make selectiv parts public in main.
19:01:52 <pboy> At later stages things may be different.
19:02:04 <py0xc3[m]> pboy: the issue is currently in stg (conflict between stg and main)
19:02:13 <py0xc3[m]> if I got your comment right (not sure tbh)?
19:04:01 <py0xc3[m]> But indeed, at the moment there is no rule to merge external MR first into stg. Do you want to change that? I have no problem with both
19:04:15 <pboy> I think, we can close the MR in relation to main, and open a new MR / commit to main using plain copy and paste and editing and proofreading. The latter should be done anyway.
19:04:56 <pboy> It's not code, it is meaningful text.
19:06:16 <pboy> External contribs into stg is a good idea for me.
19:07:14 <py0xc3[m]> pboy: I don't really understand that. So make any change we did manually again to main? Not sure if git will identify the changes to be equal. If the files have been already changed, I guess it will still see a conflict. So the branches would remain incompatible. Manual changes remain
19:07:31 <bcotton> using stage as a step between the MR and the main branch just seems like it would introduce more problems than it would solve
19:07:32 <py0xc3[m]> pboy: At the moment, the revision is intended for the MR or issue ticket.
19:07:51 <py0xc3[m]> bcotton: I think this could be true.
19:08:03 <darknao> I personally think we shouldn't use stg for editing
19:08:33 <py0xc3[m]> darknao: Indeed a good point. I think this could maybe even solve the issue widely?
19:08:40 <darknao> everything should go straight on main branch
19:09:00 <darknao> there is nothing critical, and you can't break anything really
19:09:00 <py0xc3[m]> stg is more for technical things that need testing?
19:09:12 <darknao> py0xc3[m]: right
19:09:24 <pboy> Obviously, I don't oversee anything in detail. :-)
19:10:04 <darknao> even if the doc is not perfect right now in stg, it's still better to what we have in production
19:10:05 <py0xc3[m]> darknao: +1. And see how far the issue happens again. But I think this could make other rules obsolete.
19:10:51 <py0xc3[m]> pboy: pboy: you can do MR from everywhere to main. And discussions can take place within the MR, or an issue ticket.
19:11:07 <pboy> darknao: agreed, But nevertheless, not everything is ready to get published.
19:12:01 <pboy> py0xc3[m]  yes, I see that. But obviously  various issues can arise.
19:12:52 <darknao> I guess that depends on what you mean by "ready", or more precisely, when are you considering a page "good enough" for publishing
19:14:20 <pboy> Yes, indeed. I think it should be a self-supporting, meaningful text.
19:14:30 <py0xc3[m]> pboy: this does not mean that everything has to be published immediately. You can still work in your own branch / fork. But then you know what you did and have your dedicated fork/branch only with the changes you know. This makes it easier. Not a stg with many changes throughout over a long period
19:15:58 <pboy> Not necessarpy0xc3[m]  If we want to have a reals preview, several contributors would have to merge in their contributions, I think.
19:16:36 <pboy> So, will often have a "stg with many changes throughout over a long period"
19:16:40 <py0xc3[m]> Well. I think for our texts, we can use GitLab. I need to preview. GitLab can already interpret asciiDoc.
19:16:54 <py0xc3[m]> -to +no
19:17:23 <py0xc3[m]> The remaining thing is about the technical background, which remains in stg
19:17:35 <pboy> Yeah, but preview does not mean just on article, but the context as well!
19:19:07 <pboy> A type question is how well the individual items fit together. Are connections also typographically clear. This should be seen before publication.
19:19:24 <py0xc3[m]> Hmmm... Personally, I have worked so far with the GitLab preview only and was happy with it. I can see if there is an issue in asciiDoc formatting, can check text, but I can also create a preview with the preview.sh if I need to see the outcome  in the end. But I will not insist on others doing it as well. If others feel not good with that, we need an alternative
19:20:30 <py0xc3[m]> Maybe someone has a solution for that? I'm not that fit with our framework/backend
19:20:44 <bcotton> most merge requests we get aren't going to be of the "dramatically changes the site" form, they're going to be of the "adds a single page" or "makes a minor correction". so we should focus our workflow on those cases
19:20:58 <bcotton> we have local preview scripts for when we have major changes to look at holistically
19:22:03 <pboy> Well, like I said, maybe I'm too conservative a text / book editor (a "Lektor" in German, don't know the English term).
19:22:14 <py0xc3[m]> Maybe it makes sense to change the question (I'm not sure if I understood the current problem): What is the issue that can rise if we not use stg
19:22:28 <py0xc3[m]> lecturer :)
19:22:40 <py0xc3[m]> I guess ^^
19:22:46 <pboy> Thanks
19:23:35 <py0xc3[m]> py0xc3[m]: I have to correct myself: lector
19:24:14 <bcotton> so where do we stand on this? is there more that needs to be done or do we have the immediate problem resolved?
19:25:56 <py0xc3[m]> I'm open to alternatives but for now I would be +1 to not use stg for content?
19:25:58 <pboy> I woud like to make selectively some of the changes public, py0xc3[m] and me discussed today. I don't know, if that is possible
19:26:27 <py0xc3[m]> Given the interface we use, solving conflicts can take time
19:27:05 <py0xc3[m]> pboy: If you want, we can have a talk in the next days. If I got your problem correctly, working in a fork or so should solve it.
19:27:39 <pboy> py0xc3[m]. Good for me, way very productive today. :-)
19:28:13 <py0xc3[m]> My opinion too ^^
19:28:17 <pboy> I think, a fork is a good idea.
19:28:17 <bcotton> #topic Open floor
19:28:32 <py0xc3[m]> Then we can check what the issue is, but I think your goal should be achievable without stg
19:28:46 <pboy> OK
19:28:59 <bcotton> I'd hoped we have some time to discuss this thread, but it will have to wait for next week. so feel free to discuss asynchronously
19:29:00 <py0xc3[m]> I think my last MR (which was merged into yours) is what you want
19:29:00 <bcotton> #link https://discussion.fedoraproject.org/t/the-future-of-fedora-docs-website/41706/
19:29:01 <bcotton> also
19:29:24 <bcotton> #info bcotton intends to step down from the Docs Board at the end of August
19:29:37 <py0xc3[m]> @ all: also feel free to discuss in the current MR what you think of the draft structure
19:29:41 <pboy> Rejected.
19:29:48 <py0xc3[m]> I think we can do this asynchronously
19:29:58 <pboy> bcotton: Rejected.   :-)
19:30:15 <bcotton> we're getting into the busy season for the release cycle and I need to focus more energy elsewhere, so in the interests of being clear about my ability to participate, I'm going to not pretend that i'll be more active than I can be
19:30:25 <bcotton> pboy: I reject the rejection :-D
19:30:44 <py0xc3[m]> Sad to hear that, but I understand you have other obligations in the community
19:31:16 <bcotton> We're more active than we were at the beginning of the year, so I hope the momentum carries on :-)
19:31:32 <py0xc3[m]> We will try to survive ^^
19:31:47 <pboy> bcotton I think, we still need you, at least for some time.
19:32:03 <bcotton> but for now, our hour is up. see you all next week (and also before then in the usual places)
19:32:08 <pboy> Maybe less active than currently, but nevertheless
19:32:13 <bcotton> #endmeeting