GitHub collaboration scheme

Destry · 2017-03-01 16:14:56

I’m setting up a new repo in the CSF ‘organization’, csf-glossary, for a collaborative writing/editing project concerning UX content strategist types. I’m expecting a lot of the people who would be interested in contributing will barely know GitHub, and may even be first-time users. That’s kind of the whole point, to expand their horizons out of MS Office and Google Drive. And they are the subject experts, presumably.

I’m wondering what my full range of options are for collaboration rights (access to the repo). What would be fine is something like this:

CSF ‘Organization’ = managers = direct commit rights
Repo ‘team’ = editors = outside collaborators = direct commit rights
Repo collaborators = writers = outside collaborators = request to commit rights
Project watchdogs = commenters = outside collaborators = issues rights

I’m a little fuzzy on a couple things:

For managers, no problem.

For edtors, it doesn’t work as hoped. A person can’t just be on a repo team without also being in the ‘organization’, apparently, and that’s not ideal (we don’t want unlimited editors having org rights to repos out of scope). There does seem to be a workaround, where you can first invite them to the org, add them to the desired team associated to the repo, then change their status to an “outside collaborator”. This removes them from the org and the team, but they still have direct commit rights on the repo. That’s kind of an odd hack, if you ask me, which is fine, but we ideally need a way to see who these people are (e.g. a team, or project), but I don’t seem to find any way to make that possible outside of maintaining a list of names manually. Is that right?

For writers, I’m assuming this is where pull requests come in. They clone the repo and do a pull request when they have something to merge. My question here is more of a repo structure question because I’ve not worked with pull-requests before, either as puller or requester. Can this work with just a master branch only? Or do I need to create a staging branch or something for pull requests, then merge the staged commits to the master? I don’t mind learning how to do that at my end, but I want to structure the repo in a safe way and I need to know how to write the user docs for these people.

For the commenters, they only need the ability to create and/or reply to repo Issues, not clone, commit, or pull request. But is that kind of access to ‘issues-only’ allowed?

Thanks for any clarifications or suggestions.

Bloke · 2017-03-01 18:48:20

I don’t know the specifics of the ‘hack’ you mention but I can say that, for the writers, having a single master branch is absolutely fine. Potential committers clone from master and issue a pull request back against master. You review it, and either:

hit Merge to pull the changes directly to the master branch; or
add a comment asking them to refine it; or
clone master yourself to a local repo, download their PR to a dedicated branch, tinker with it, checkout master, merge the changes from the PR branch into it and push master back to the server (then optionally delete the local branch you made).

Option 3 seems like a faff, but if you click command line instructions next to the Merge Pull Request button, it lists all the stuff you need to do.

Hope that helps.

Destry · 2017-03-02 08:15:11

It does indeed help. Thank you, Bloke. I’ll try and keep it a simple 1-2 punch for now.

The ‘hack’ I mention probably isn’t a hack, per se, since it’s all functionality through the web interface, but the way it’s designed, conceptually, seems like a hack solution to me… Like they didn’t think it all the way through, or what other options collaborators would want/need.

That there’s no way to actually point to the people on a repo who classify as “outside collaborators” (vs. org members) seems strange to me, as example.

Destry · 2017-03-11 11:28:32

Destry wrote #304325:

we ideally need a way to see who [outside collaborators] are (e.g. a team, or project), but I don’t seem to find any way to make that possible outside of maintaining a list of names manually.

I found where these people are listed, but it’s just one comprehensive list for all outside collaborators for all the org’s repos. Still, that’s better than keeping a manual list because we don’t have but a handful or such people. ;)

Bloke wrote #304326:

Potential committers clone from master and issue a pull request back against master.

I tried this, but it doesn’t seem to work. GitHub tells me (at least via the desktop client), that a PR can’t be made directly from a clone to master. (That kind of makes sense to me, considering that’s the scenario someone with direct commit access would use; no need for PRs.)

Then I was looking at this from GitHub docs about collaboration scenarios, and though it’s not entirely clear to me what they’re saying, I think they’re saying a person has to:

clone the master
create a local branch (e.g. ‘my-drafts’) of their clone (the branch being independent of the master at that point)
make changes in the local branch, and do a PR from the branch.

For those people, then, the entire workflow is somewhat circular, it would seem. Does this model seems correct?

I didn’t choose the fork direction here because it seems to me that’s an option when the collaborator wants to spin-off the project on their own, which nobody will want to do on this. Plus, by cloning and working from a branch, they can later work directly from their clone if they ever decide to word at the editor level with push rights.

Destry · 2017-03-11 11:40:43

Bloke wrote #304326:

Potential committers clone from master and issue a pull request back against master.

It just occurred to me that maybe this didn’t work in my test because I already have direct push rights (repo admin). Maybe the GH client recognizes the fact and discourages a PR in that case? I don’t know.

Destry · 2017-03-11 11:49:39

@Phil (or anyone),

As that model indicates, the glossary will end up being a Jekyll site just like the Txp docs. This will be better than having to have a manual porting phase to a CMS later. (I will need to see if Oleg’s nifty glossary index script will still work in that case, but one bridge at a time.) Can you give me the 5-year-old’s version of steps/links here to get me on the right path?

For example:

Install this.
Get that.
Load the other.
etc

I’m look at the Txp docs repos, but not sure if there’s a necessary order to things, if stuff must be loaded locally first, if I need a Jekyll-friendly editor, etc.

Much appreciated.

philwareham · 2017-03-11 13:52:18

First thing to do is set up a GitHub Pages format repo – instructions here

Note that if you want to use your own custom domain name and also HTTPS then you’ll need CloudFlare – instructions here

I’ll write some more instructions later, going out now.

Destry · 2017-03-11 21:17:40

philwareham wrote #304583:

First that to do is set up a GitHub Pages format repo – instructions here

Great. Thanks. I presume I wouldn’t want to do that until the files are somewhat ready to go first, though, right? Or does it really matter?

Destry · 2017-03-11 23:14:58

Just to follow up with my journey on pull request scenarios. I got it directly from GitHub Support that PRs have to be done from a fork.

But then I wondered how can a person keep their fork up to date with the master repo if they can sync it like a clone?

And there’s an answer: Keep your fork synced. But, geez, that’s not something anyone afraid to step out of MS Word is going to do. That will scare off potential writers before they event want to try.

I may have to make anyone who wants to contribute an “outside collaborator” on that repo and give them push rights just to lower the bar as much as possible. Apparently, this is the only way they can add labels on issues too, which is also rather central to the communication side of our collaboration (heavy use of custom labels).

Alas, there’s only so far you can un-technify GitHub for writers, me thinks, which won’t be quite far enough for some people. Still, it seems ideal in this case considering the repo will feed the production site without additional processing.

/just talkin’ to myself at this point/

maverick · 2017-03-12 01:49:05

Destry

I’m working on several writing projects that would benefit from collaboration and version control. I’m not sold on Github as viable option (it seems complicated, especially for the basic tech audience I’m working with.

I’m curious about the benefits you see in using Github for versioning control rather than something a bit more tailored to writing projects – like Draft, Penflip, or ShareLaTeX, or even Dropbox’s Paper?

Destry · 2017-03-12 11:13:03

maverick wrote #304616:

I’m not sold on Github as viable option (it seems complicated, especially for the basic tech audience I’m working with.

I hear you. I’m painfully aware of that tech-leary writing crowd. And you would think these people would have disappeared by now, but there are still armies of writers out there whose jobs don’t require anything but MS Office. I even know content strategy consultants who avoid Markdown at all costs, to say nothing of something nice like Textile.

That said, I think GitHub (or any similar versioning platform) does have something to offer in certain cases like mine, and this might just be a special case scenario.

I’m curious about the benefits you see in using Github for versioning control rather than something a bit more tailored to writing projects – like Draft, Penflip, or ShareLaTeX, or even Dropbox’s Paper?

I’ve not used ShareLaTeX or Dropbox Paper, so I can’t speak to those. But I have used Draft, Penflip (early on), Gather Content (which CSF is publishing a review on soon), and Google Docs (of course).

We even tried using G Docs for the drafting phase of this project (realizing we’d have to manually port all the drafts to the publishing system later), but it was just too cumbersome for the communication side of the collaboration. The little margin comments in a doc was out of control and too hard to manage when you have more than a handful of people working together. Plus there was no real good way to track the status of a given draft. Further still, G Docs are a poor choice when the collaborative writing is on many pages of web content (unless production location is wordpress.com and group is using something like Wordable).

Draft is a nice enough tool for collaborative drafting of one-off articles, but for my project it would suffer the same communication issues we experienced with Google Docs. It also lacks the publishing gears to go directly from Draft to publishing system without a lot of manual porting and format fiddling in between.

Penflip is actually a writing layer on top of GitHub, so that could be closer to the goal. But if I remember correctly, it’s designed around writing textbooks, not web copy that can be published directly from source. Can you put a Jekyll site on the front of a Penflip project? I don’t know.

So, before I make a case for GitHub, let me summarize the glossary project… Rather, just read this. In fact, consider the built-in wiki for writing/centralizing all the project documentation — in context of the repo — a big plus in favor of GitHub. But the short of it is:

A rolling (ongoing) project over time.
Many people with varying skills and backgrounds (thus a lot of debating).
The need for decision making controls in addition to the collaborative writing/editing components.
The need to control access without having to actively grant access to anyone wanting to contribute. (This is where PRs shine.)
Many expected definition drafts (making up the glossary), which represent individual web pages.
The desire to have the lowest amount of overhead between a draft file becoming a production file. (Meaning they must ultimately be HTML ready without writers having to work in a lot of HTML.)

With that in mind, you might be seeing where GitHub has an advantage in this case, but let me highlight the three biggest factors that favor GitHub over other collaborative choices:

Wiki docs
As mentioned, the wiki for project docs is essential. If collaborators don’t have a clear docs base to find self-help, the project doesn’t get off the ground. Of course, the burden on this is on the docs writer whether docs are good or not, but the proximity of these with the repo in GitHub is a big advantage on top of the docs existing at all.

Communication collaboration
Besides knowing how to collaborate and communicate by working protocols, which the docs help make clear to people, the platform must provide tools to help with the communication side of collaboration too. As mentioned, Google Docs failed us here. But GitHub’s Issues with their customizable labels is a fantastic way to record decision history and current status of each working definition. Each term in the glossary has it’s own Issue where all historical debate and status are recorded and easy for collaborators to monitor.

One setback here is that collaborators who don’t have commit rights can’t apply labels on an issue. I didn’t realize this until yesterday. :{ I contacted GitHub and they said it was a common gripe/request so they added my +1 to the request. (Make the request everyone!) We have a choice to make here now:

Just give all contributors commit rights (which means no PRs allowed), or
add another doc explaining that pull-requesters must look at our labels and make a mention to @wion (etc) that they want x, y, z lables added, and the admin will have to do it. That sucks, of course, but it’s one way to approach it.

Live-update website
The brilliance of this for this project only hit me recently. I was expecting to use Txp for the production site, but a Jekyll site that’s powered directly from the repo files is 100x better in this case. Look no further than the Txp docs and you begin to see the advantage and efficiency when all said an done. And because the files are not written in a regular HTML-standard way, they are more feasible for writers to digest and work on.

And look at a typical file, where the metadata is in a grid across the top. That’s typical of a “page table” model that copywriters are familiar with, so it will be useful for collaborating writers who must ensure each page has associated microcopy too. In other words, there’s a fairly decent amount of separating content from presentation, and that helps lower the bar to potential collaborators while also lowering the overhead to technical editors who would otherwise have to manually format every page into something production ready. With GitHub/Jekyll it’s all one thing.

And beside all the technical considerations, we’re also doing this in a small part as a educational opportunity; a chance for people to learn something a little outside of their regular humdrum routine. (I learning a lot by diving into being a repo manager and writing all those docs.) Because if they live inside MS Word every day, or even Google Drive, they’re not expanding their horizons.

Anne Gentle has been tackling this notion from the side of writing user documentation, as she covers in Docs Like Code. And I know a guy on this project, where they use GitHub to manage the DITA OT. That site is a powered by GitHub too, I think.

We’re not dealing with documentation, exactly, but we are creating a written product more than an application. We’ll also be making sure the glossary fits into a semantic hierarchy with schema.org, so that’s part of the experiment too, which is also increasingly important for our writer crowds to understand.

maverick · 2017-03-12 11:45:28

Thank you for sharing your insight and experience Destry. That provides me with a good deal to consider as I move my projects forward.

Good luck on your project!

Textpattern CMS

Textpattern CMS support forum

#1 2017-03-01 16:14:56