Preventing Build Errors on ph-submissions

[walshbr]

The broad proposed action here is that we rethink how we ask authors to upload materials to the ph-submissions repository or otherwise think through the editorial workflow slightly differently.

Ph-submissions has people push directly to it rather than make pull requests (presumably for ease of use by authors). But this means that if the site gets a build error the results are a little more hidden than they would be on our site. You get an email, but the email can be easy to ignore because it won't block the contribution from being part of the repo like it would in a pull request. Here’s an example screenshot of the commit log:

There was an issue introduced several commits back that broke the site build, so it stopped rendering properly. The issue with this is that, until the build error is fixed, the build will continue to error until someone fixes it. And it won’t build on the subsequent pushes. That means, for example, that if I had had looked at the live, rendered version of my lesson in progress that I just committed to I might be wondering why changes I pushed weren’t showing up. The errors persist until someone notices them and fixes them, and there’s not really anyone tending to them. Most of the errors eventually get ironed out in the review process, but that can often take a while. They’re primarily errors introduced by authors who have made mistakes with the metadata or include syntax for figures. The build error here actually wasn’t resolved until made changes to four different lessons in progress. No one is really tending the repo in that way, and there's not a good process for making sure that those sorts of errors don't take place.

We discussed this a little on the technical team slack how we might avoid this sort of thing in the future. The consensus that I'd like to propose is the following:

• We tweak the editorial process to have the editor for a lesson post the initial file for the lesson and, in the process, make a first pass at making sure the metadata is formatted correctly.
• We make a note about how the editorial/translation process should involve checking the commit log for build errors and show where to find them in the web interface (I don't think this is in the guidelines, but I might have missed it while re-reading just now).

That would catch most of the errors I think and give a process for making sure they get caught regularly as part of the process.

[jenniferisasi]

I realized that we don't have a tag for "editors only" or similar so this might be missed by them. I am pinging @rivaquiroga @spapastamkou and @svmelton for a quick check as MEs. And maybe we need that tag.

[walshbr]

Good point and thanks!

[rivaquiroga]

This is a very good idea. And you are right, checking the logs is not on the editor guidelines. Actually, in case the rendered version of the page doesn't work, the propose solution is: "let Matthew Lincoln know, and he will try to diagnose it". This is something we editors should try to solve first.

[jenniferisasi]

Oh no, right, that "contact Matt" solution is NOT good at all. In theory, authors/translators should be using the templates with the YAML in place, etc. but...

[walshbr]

No wonder he's retiring!

[mdlincoln]

"let Matthew Lincoln know, and he will try to diagnose it"

[rivaquiroga]

Some actions arising from this issue:

• Update Author + Editor + Translator guidelines regarding who uploads the initial file for the lesson

• Update Editor Guidelines for checking any build errors after commits from authors/translators

[spapastamkou]

Would it be simpler to ask authors/translators to make pull requests reviewed by the team members instead of commiting directly? Or not?

[walshbr]

Simpler in terms in one sense, maybe, but it would mean that we might have to give people guidance on how to submit pull requests I think. So the burden on authors becomes a little more complicated.

[svmelton]

Just noting that I think this is a good solution—thanks @walshbr!

[walshbr]

Seems like there is consensus among the managing editors that this is a good idea, so I'll make these changes to the guidelines.