Developer Commons workflow

[ion-oset]

A conversation to discuss a workflow for the developer commons. The main idea is to make use of the features of GitHub to start with free-form discussion and get iteratively more formal via issues, PRs and projects and source as ideas turn into proposals and actual practice.

Following that workflow the proposal for it is on the wiki: Developer Commons - proposed workflow.

All feedback welcome.

[stratofax]

It seems that this Discussions area is a better forum for brainstorming, and that policies and guidelines should move to the wiki only after we've reached some consensus on it (like, say, Naming Conventions). Then, as noted in the workflow wiki page, we can formalize our consensus using the Issues tracker.

I'm making a distinction between brainstorming and notes. Notes could include a list of links to (again, as an example) good articles about Python naming conventions, PEP documents, and notable code repositories. Notes could also cover first hand accounts, like gotchas using a package manager. It makes sense in my mind to capture this stuff on the wiki.

But for things that entail an opinion, like "what's the best way for OSET to name variables," I think it's best to work it out here in discussions, reach consensus via Issues, and then publish to the wiki.

So: notes = facts; brainstorming = opinions. The wiki should be, IMHO, a definitive reference for the OSET team, and if an opinion appears in the wiki, it's there because it's been vetted by the team.

What do you think of this opinion?

[ion-oset]

After our conversation on Tuesday I mostly agree.

For the record the primary distinction I want to make is between informal and formal. I believe it's very useful to have clear space where we can brainstorm separate from clear space where we are being rigorous. I saw the Discussions and the Wiki as being "informal" and the issues, PRs, and source repository as "formal". I think this in part from intuition about forums and wikis but also to a degree because GitHub itself seems to treat them that way: discussions and wikis are both open to all collaborators, discussions can be turned into issues, and so on.

From this viewpoint the way Discussions interact Wiki pages is similar (but better) to collaboration works with Slack and Google docs: there is simultaneously a conversation happening about an idea or document in development, and notes or drafts are being referred to. The first is the real time brainstorming the second cherry-picking what we want to highlight and keep.

After talking in person I agree though about the slightly but important difference you are calling for. It would be useful to be able to tell people "if you don't know where to start, look at the wiki". Since GitHub Wiki has very little structure (no sub pages, and, even more significantly no labels) there's no easy to way to separate what is a draft or random notes from what is at least somewhat curated.
But Discussions do have labels, and they do have structure. There still needs to be a place to summarize the conclusions of the discussion, but there we benefit from the fact that the top post of a discussion is editable by members of the team. We can elevate the conclusions to the top post. All discussions and posts also have URLs, so we can link to them.

...

Please note that though I strongly believe this should all remain informal. Wiki and Discussions should be a sandbox. People can try ideas out and have them not go anywhere. Wiki pages can be edited without a lot of discussion (or at least announced after the fact). We can add water and make the sand hold a shape we like.

However when we adopt a proposal of any kind and it goes in the source tree, it's because it's been _formally accepted. This should follow a formal workflow, with an issue created, PRs for formal review, and agreed upon steps for acceptance. This should be just as true (if not more so) for convention and policy as it is for code. There's going to be some overlap between what seems to go in one place or another. But this is a line I think we need to hold and be clear on.

[ion-oset]

All this allows for a breakdown like the following.

Use Discussions for any topic where you want feedback.

• Informal brainstorms
• Questions
• Proposals that you want review on

If a discussion proves fruitful and there's good ideas in progress, elevate them to the top post (either directly, or as links).
Use labels to show the status of the discussion just as with other GitHub documents (no label would be default to meaning informal).

Use the Wiki for re-usable resources:

• Collecting external references on a topic (e.g. particular open source standards, best use of a particular library)
• Collecting internal references (e.g. links to good ideas from our discussions)
• A draft proposal that is has some consensus but has not been formally adopted (what IETF, W3C and others call "strawman proposals")