[Improvement] Simple workflow

[kappapiana]

A basic workflow for contributions

I propose to adopt a workflow for changes to the project, based on three levels of branches, to mimic the workflow of software projects. This would help people to contribute in an ordered way.

Branched structure

Invariably the workflow has the top-level branch (master) as a protected branch that only changes any so often, by merging commits from development branches. So basically we would have

a. Main branch

Or master Only touched for major or minor versions changes. The branch is protected, only maintainers can write on it. It does not receive commits directly, but merges from the development branch.

b. Development branch

Is the target branch for pull requests to receive added features or for quick and dirty bug fixes. If it's a quick fix or a small addition, no point making it more complicated. But also no risk to publish for large consumption some half-baked stuff or stuff that would be reverted later.

c. Feature branches

Feature branches are branches that ideally are developed on forks and then pulled in via pull requests.

Some more important sub-projects might be authorized to open a feature branch directly in the main repo and other people could then open pull request to the feature branch instead of the development one.

The workflow

A developer first thing forks the project and works on a new feature branch in the forked repo (can be called feature-something or patch-something or fix-something depending on its nature: substantial addition, small addition or quick fix). Once it's ready, a pull request is made using development as target. If the change is approved, the PR is merged into development, which is the unstable version.

At some point a feature freeze occurs, the content of development is looked at as a whole, see if the additions are ok and consensus is collected and a new version is merged to master, creating a new version, which is labeled accordingly.

Exceptions

Some might be intimidated by this process and just prefer to bring a change through opening an issue. A volunteer should then show how the proposed change could be done and teach through learn-by-doing how to achieve the end result.

Advantages

The master branch will remain a reliable source of information. But people wanting to live on the edge can peek into development to see a more lively, yet possibly inaccurate or prone to change set of documents. We will only have one document instead of multiple documents with different versions. The history is however preserved, through version flags and by inspecting the git history.

Requisites

A developer must have working ability to:

• edit a document in a git environment (either directly on the Github platform, or locally and then push it)
• create a branch and switch to it
• fork a repo
• create a pull request and identify the correct target branch (never master)