Hi Shuah,

After a small administrative hiccup, I was able to port my prototype to the ELISA Orientation Repo[1][2] (probably better known as Onboarding - difference being that it should be a repo for general internal project information, directed not just at newbies).

As agreed, the Onboarding document is there in its original form, but the repo is not quite ready for prime time. Before letting content developers loose on it, I intend to produce documentation in the wiki for:
- the workflow for contributing to the site
- the workflow for reviewing contributions
- installing and using the toolchain (with links to the documentation for the tools)
- tips and tricks about how to achieve certain document patterns

I started writing the contribution workflow and coincidentally Jochen Kall started writing a contribution workflow for the Automotive working group at the same time. We came to insight that the workflow, being based on git and GitHub, was generic for all the ELISA working groups.

I therefore decided to write a contribution workflow, directed at git neophytes, in kramdown and put it in the content of the Orientation repo rather than in the wiki.

I now propose that there be a new section in the Onboarding website for "Good Practices". As a start, this would contain
- a GitHub contribution workflow
- a GitHub review workflow

A further possibility is a document for graphics, both in presentations and in web pages. At the moment, if they are available at all, they're not necessarily stored in an optimal format. They may have also been prepared on tools only available on an OS which comes from the north-west corner of the US. A unified colour scheme would also be nice.

The first draft of the GitHub Conformance Workflow is now in the repository[1] as a (already partially reviewed) pull request. Jochen and Paul Albertella have already provided invaluable feedback. As of now, there have been 3 approaches to the process.

The GitHub black belts will be able to view the finished document in the pull request, although the kramdown markup is not recognised. The finished document can be viewed from my GitHub website[2].

I might get the review workflow in some sort of form by next week (or maybe not... after all, I'm a gentleman of leisure). It may be as well that Jochen, Paul and I will have to hash things out before writing starts.

A number of issues have emerged:
- First of all, do we want to develop Good Practices in the orientation repository.
- Is the Orientation repo's GitHub Pages website where we want to make this information available
- How exactly do these documents get approved for publication - who approves them (i.e. is this a TSC or Ambassadors responsibility), who reviews them, what level of review is sufficient
- on the "meta"-level:
- What do we need for DCO
- Is name and email address from the .git/config sufficient
identification for sign-off
- Do we want to encourage/require GPG signatures for sign-off
(has the advantage that every commit is signed off
automatically, but is added effort to install)
- Since GitHub enforces 2FA, is the GitHub Id sufficient as
a signature
- Do we want to enforce issue tracking
- before the start of work
- References to issues in every commit or just in the
PR
- Do we want PRs acked by the reviewers (got to check if the
check can be automated)

Thanks to Paul and Jochen for their support.

I suggest adding this topic to the agenda for the weekly sync meeting next week. I'm sure that by then, everybody that's interested will have read the document and responded to this e-mail. Maybe we can take a look at the document and do a dry-run of the review workflow.

[1] https://github.com/elisa-tech/orientation
[2] https://elisa-tech.github.io/orientation/
[3] https://openjohnmacgregor.github.io/ElisaPages/GitHubContributionWorkflow.html

Cheers

John