Documentation for work flow

[ghost]

This issue is part of issue #132 that intends to clarify and document the work flow of current interim maintainer @clearkimura. Future contributor may use this work flow as starting point.

Then: Less proper way

What I have been doing as documentation contributor is a linear commit. Push updates to modified documents directly to master branch and pages on Wiki. This is straightforward and easy to do for one-time update. But when this way becomes a habit, many commits are pushed just like that without discussion or clarification.

Now: More proper way

What I am doing now is "more proper" than before; By creating a new branch from master, commit changes, test, repeat cycle, then create pull request to merge changes from the branch to master and finally merge changes to complete the process. Similar to the way explained by GitHub work flow.

Yet: How proper

To plan work flow, one need to understand three things on GitHub:

1. What are milestones and how it is used? (milestones and issues)
2. What are branches and how it is used? (branches and pull requests)
3. What are releases and how it is used? (releases and release notes)

When following work flow, one may realize there are few missing details:

1. What is semantic versioning X.Y.Z and how it works?
2. What is change log and how it is different from release notes?
3. When to update change log?
4. When to create/tag a new release?

And finally, the work flow itself that illustrated from start to end (perhaps as a text chart?) -- this and all above shall be documented in repository at docs/workflow.md.

How to text chart

One way is to clone the "old stable" repository to local system and run git command to show relevant output. This was hinted by Git documentation in Chapter 3 Git Branching.

Example output copied from the link:

$ git log --oneline --decorate --graph --all
* c2b9e (HEAD, master) made other changes
| * 87ab2 (testing) made a change
|/
* f30ab add feature #32 - ability to add new formats to the
* 34ac2 fixed bug #1328 - stack overflow under certain conditions
* 98ca9 initial commit of my project

This copy-paste method is perhaps more practical and easier than drawing text chart in horizontal direction. No need to create example work flow, just show what we already have and explain.

Purpose of documentation

When the work flow is proper, one can easily see how the project undergoes changes over time. Despite being an interim maintainer for several months now, I am yet to define "proper" work flow.

In related matter, commit history for both 4.1.2 and 4.1.3 might have been oversimplified because I had all changes made into a single pull request and selected "squash and merge" option. This is not necessarily a bad thing, but it is not informative when seeing such commit history.

By documenting the work flow I have tried during this short interim period, future contributors will have some clues before contributing to this project on GitHub. Even better, they could come up with better work flow that I had not discovered.

I hope to include this documentation in the next patch release 4.1.4.

[ghost]

Patch release 4.1.4 has better commit history compared to 4.1.2 and 4.1.3, which were both oversimplified by several pull requests and "squash and merge" option. The git command output has been added to docs/workflow.md and that shall conclude this issue.

Remaining topic "Future work flow" shall be updated after observing next milestones.