Editing via direct commit vs. PR

[mdlincoln]

Re: convo in #626

Our current advice for how members of the editorial team should edit the site is a bit of a mishmash, and it's causing confusion: https://github.com/programminghistorian/jekyll/wiki/Making-Technical-Contributions

As author of those ad hoc contribution notes: I am sorry! They're clearly not working well enough for us.

At present, it is possible for team members to make commits directly to the gh-pages branch of this repository, which directly updates the live site. It's also possible for authors to create pull requests (PRs), which stage the changes for review before they get merged into gh-pages and "go live". By allowing authors to just make direct commits, this reduces quite a bit of the technical burden on the editorial team: you don't have to know how to create new branches and PRs in order to add or change content on the site. However, by not requiring all changes to be made via PR, we lose some of the great infrastructure like web previews, inline commenting, and formal reviewing that GitHub offers us.

As the site has expanded, and we have introduced more complex integration between pages (both through metadata checks and complex Jekyll templating, or Spanish translations), it's getting harder and harder to correctly edit the site by yourself.

It is possible to set GitHub to only allow edits via PR, and even to require that all PRs be subject to formal reviews by a team member. This would definitely ensure consistent editorial practices... but it would demand that anyone making edits would need to be able to use the PR system. This would make the editorial learning curve that much steeper.

Alternatively, we can continue allowing changes to happen directly to gh-pages, but reiterate that editors need to be very consistent in checking the Travis build results and pinging the Spanish team when necessary.

I'm also open to other suggestions for how we can better clarify processes.

[drjwbaker]

Thanks for the detailed start @mdlincoln.

I'm in favour of using PRs for any changes to any wysiwyg text in any part of PH. In this process those raising the PR should nominate reviewers: one content reviewer, one ES to check translation implications, and - in cases of lessons where more than minor edits are being made - an author. The latter would not have to approve but - I think - should be notified and this gives us a mechanism for doing that.

Everything else can be handled by being sensible and asking for review if you've done lots of work if you think it would benefit from checking (as we've been doing with #612, for example)

[ianmilligan1]

Agreed, this is a great conversation to have @mdlincoln!

I think this is a good practice, leveraging the platform to make our workflow more systematic. I think there'll be a learning curve but once we get through that things will be good. I think we should also make it clear that folks are not to merge their own PRs, however trivial they might be. And I think we can set it that each PR needs a reviewer approval.

[acrymble]

I suppose the PR approach, but I don't know how to do it properly. I've never understood what I'm supposed to do and I find it unintuitive, so I'd need some clear instructions.

[acrymble]

This can be closed thanks to @ianmilligan1 documentation, no?