[lsb-discuss] workflow and git diffs

[Robert Schweikert]

As we move forward with the "new" stuff it turns out that the workflow 
as documented in the README.md file where documents move through stages 
in the repository is not really working. The problem is that this 
produces some ugly diffs which makes it difficult to figure out what is 
going on, see: https://github.com/LinuxStandardBase/lsb/pull/6/files
  as an example.

In this case the file userNaming.txt, which had an accepted problem 
statement and therefore was located in the documents/problems directory 
was moved to documents/proposals while at the same time adding a 
solution proposal. This follows the initial workflow that we documented 
in README.md. While the initial idea is appealing and would make things 
easy to track I no longer consider this workable, simply because of the 
diff that gets generated due to the move of file.

I therefore propose to change the work flow a bit:

- We create a documents/wip (or another suitable name) to hold all 
documents for "issues/problems" we are working on.

- The template that should be used for documentation purposes gets a 
"Status:" entry at the top that indicates the status of this document. 
Accepted values would be "Problem Statement", "Proposed Solution", 
"Solution Accepted".

- After a document changes from "Proposed Solution" to "Solution 
Accepted" it gets moved to documents/specifications

- The only changes that should occur once a document has reached 
documents/specifications are additional "pledges" by distros to support 
and implement the solution and spelling mistakes.

This approach should avoid the ugly diffs we experience with the current 
pull request and should still give a reasonably quick overview of the 
stuff we are working on and what state that stuff is in. We can even 
have a little script that polls the "Status" line of each document in 
wip and then creates a web page to display the status.

Thoughts/Comments?

If there are no major objections I'll update the README.md file to that 
effect. We will still have to deal with the ugly diff for stuff that is 
currently in progress.

Later,
Robert

-- 
Robert Schweikert                           MAY THE SOURCE BE WITH YOU
SUSE-IBM Software Integration Center                   LINUX
Tech Lead
Public Cloud Architect
rjschwei at suse.com
rschweik at ca.ibm.com
781-464-8147