Incentive for authors to get their posts done more quickly

[AngelOnFira]

I try to also use it as incentive for authors to get their posts done more quickly :)

that's something worth noting in the newsletter issues or readme 😅

Originally posted by @PsichiX in https://github.com/rust-gamedev/rust-gamedev.github.io/issues/852#issuecomment-988159320

[AngelOnFira]

@ozkriff @17cupsofcoffee I'm interested in your thoughts, since this re-ordering is something I've mostly done on my own. How do both of you handle section ordering? Is it worth adding some info about it to the template?

[PsichiX]

ngl, personally if i knew FIFO ordering is used, i would prepare my notes week before xD before i knew these ordering shenanigans i've been late bc i always prioritized my day job work knowing order doesn't matter here, so now that information changes everything :D

[ozkriff]

I thought that all the editors have agreed on FIFO ordering after a Discord discussion many newsletters ago. At least I've trying to follow it for many months now.

It certainly makes sense to document this in the coordination issue template.

[Bromeon]

What is somewhat inherent to the one-page format, but also causes extra work (for both editors + authors), are the constant merge conflicts.

Maybe some alternative approaches should be brainstormed, e.g. having a "include" statement which is simply copy-pasting the contents of another .md file into its place? That would allow independent and parallel work. I'm not sure if there are any Zola or Markdown extensions for this, but even a simple Rust/Bash/... script run through CI before sourcing Zola could already do the job.

Ordering could still be done in a FIFO style if that is desired. It means however that people with the most time/availability always have their entries at the top, and people with a tougher RL schedule are extra punished. Maybe random order is fairer in that regard.

[ozkriff]

@Bromeon Personally, I love the simplicity of the current one-page format and that it's easy to preview on GitHub as-is.

causes extra work (for both editors + authors)

:thinking: The authors aren't supposed to resolve any conflicts and for the editors it should take something like 10-30s cause the sections are modular and the conflict resolution before the merge is fairly easy even with GitHub's web UI.

[AngelOnFira]

It means however that people with the most time/availability always have their entries at the top, and people with a tougher RL schedule are extra punished

People always have the option of preparing their work before the month starts, or the issue comes out; it's no secret how it will work each month. The problem is that we tend to see more people submitting after the "soft deadline", which is normally several days into the month. That could extend across an entire workweek, but again, people can pre-emptily prepare if they want to have their section at the top.

Further, the merge conflicts that we have right now aren't the end of the world. It does mean that we have to add another commit when we go to merge, and CI does have to run again, but PRs get squashed so it's not too dirty. It is currently the lowest-overhead solution, which works well since editing the blog each month is already a very heavy load on the three editors :sweat_smile:

[Bromeon]

I see, thanks to both of you for that perspective!

What I'm not yet sure about are author PRs that need changes. I guess it's less stressful for editors if we provide PRs before the month ends. If some changes are requested only weeks later, it could still mean a lot of last-minute ping pong (and last place + merge conflicts for that entry) 🙂 but if it's not the rule, should be totally OK.

My takeaway: we should ideally submit in the last week of the month (or even earlier). Won't this "race" eventually have the effect that the reporting window shifts to a few weeks earlier (so it's not really about November, but about mid-October until mid-November, for example)? Just thinking loud, I agree all of those are not huge issues 😉

[Keavon]

Just a thought: what if we could submit our content as markdown directly in a GitHub issue instead of dealing with the (franky very frustrating and laborious) process described below?

• Updating our existing but outdated fork (usually it's easiest to delete my entire fork and make a new one in GitHub)
• Cloning it to our computer (which is several hundred megabytes)
• Writing content
• Dealing with annoying linting requirements
• Submitting a PR
• Then fixing lint errors from CI and pushing amendments until it passes

Avoiding this technically challenging and mostly mechanical busy-work would probably help improve both the speed that people submit sections as well as the number of sections people are willing to write, by removing the barrier to entry so that it can be a simple matter of commenting on an issue, or filing an issue, with the post's markdown directly included in the post.

[Bromeon]

@Keavon the disadvantage I see is that you can no longer preview it in Zola (locally) and no longer run CI. So it effectively moves more work from authors and automation to editors, which then have to manually put each entry through the linter and fix it or request changes.

But I agree that the linter is a bit strict. Is there maybe an option to auto-correct some of the changes? Such tools should have no problems replacing * with - in lists, or removing extra lines between paragraphs. IDE integration might be even better; I'm not sure if VSCode is the only one at the moment.

[Keavon]

How about removing the linter entirely? I see no point to having it. Markdown is meant for humans, not computers. (Specifically: who does it benefit? It's "nice" to have standardized markdown source, but as soon as the newsletter gets published, the markdown gets rendered and nobody goes scrutinizing the source ever again. Markdown is a means to an end so formatting should be up to conveniences of the author. It isn't code.)

[17cupsofcoffee]

My thoughts:

• I also usually go with FIFO ordering unless one of the other editors specifically asks for it to change. The only time I generally reorder things when editing the newsletter is when multiple sections have a common 'theme' - e.g. i'll group all of the Ludum Dare games in a month together. I'm not 100% sure if we'd want to make this an explicit incentive, though? Promising people we won't change the order after their PR gets merged feels like it could give us less flexibility/increase the overhead of resolving merge conflicts.
• Merge conflicts aren't one of the major pain points for us as editors, I don't think? Maybe we could make it clearer in the guidelines that we'll resolve those before merge, rather than people feeling like they have to endlessly rebase their PR.
• I'm (slowly) working on finding a fix for the repo clone size on #636, as I recognize that's a big problem for contributors. I'd personally recommend people use the web editor rather than editing locally, but I know that's easier for some sections more than others.
• I don't like the idea of taking section submissions via GitHub issues, as that would make it much more difficult to do reviews and would require a lot of extra manual assembly by the editors.
• It would be really nice if we could auto-apply fixes, but I have a feeling GitHub Actions might be too limited :(

For discussion on the specific linting rules, it might be worth redirecting that to https://github.com/rust-gamedev/rust-gamedev.github.io/issues/639? @ozkriff and I have already posted some thoughts about the benefits and drawbacks of the current rules there.

[janhohenheim]

In my opinion, this should be fixed now. https://github.com/rust-gamedev/rust-gamedev.github.io/pull/1480 removed most lints and https://github.com/rust-gamedev/rust-gamedev.github.io/pull/1482 introduced a freeze period starting on the 28th, after which all new submissions will be moved to the next month. I'll close this issue for now and reopen it if new problems come up :)