[V2,0/3] Formatted INFO files to fit Markdown (.md) format.

Message

Yoni Bettan Sept. 2, 2018, 5:53 p.m. UTC

This patch make INFO files (e.g. README, CODING_STYLE and HACKING) much more
readable when watched from GitHub GUI.

./VERSION, ./MAINTAINERS were leave untouched otherwise
./scripts/get_maintainer.pl breaks.

./COPYING, ./LICENSE ./COPYING.LIB were leave untouched because it look likes
they come from GNU and not QEMU. 

Visualization of the change can be found at
https://github.com/ybettan/qemu/tree/md.
NOTE:
This last part of the message should be removed from the commit message
since I will remove the 'md' branch from my fork if the patch is
accepted.

Yoni Bettan (3):
  README.md : Formatted to fit Markdown (.md) format.
  CODING_STYLE.md : Formatted to fit Markdown (.md) format.
  HACKING.md : Formatted to fit Markdown (.md) format.

 CODING_STYLE => CODING_STYLE.md | 151 ++++++++++++++------------
 HACKING => HACKING.md           | 186 +++++++++++++++++---------------
 README => README.md             |  89 +++++++--------
 scripts/checkpatch.pl           |   2 +-
 4 files changed, 223 insertions(+), 205 deletions(-)
 rename CODING_STYLE => CODING_STYLE.md (50%)
 rename HACKING => HACKING.md (53%)
 rename README => README.md (67%)

V2:
- Undone the changes on ./LICENSE
- Updated scripts/get_maintainer.pl to reference to README.md instead of README
- Repaired broken link to ./LICENSE in ./README.md

Comments

Daniel P. Berrangé Sept. 3, 2018, 9:45 a.m. UTC | #1

On Sun, Sep 02, 2018 at 08:53:58PM +0300, Yoni Bettan wrote:
> This patch make INFO files (e.g. README, CODING_STYLE and HACKING) much more
> readable when watched from GitHub GUI.
> 
> ./VERSION, ./MAINTAINERS were leave untouched otherwise
> ./scripts/get_maintainer.pl breaks.
> 
> ./COPYING, ./LICENSE ./COPYING.LIB were leave untouched because it look likes
> they come from GNU and not QEMU. 
> 
> Visualization of the change can be found at
> https://github.com/ybettan/qemu/tree/md.

As Peter mentioned on v1, QEMU has decided on using RST for docs, so I agree
with him that adding Markdown is not desirable.

As you can see from existing docs, GitHub knows how to display RST nicely
already:

  https://github.com/ybettan/qemu/blob/md/docs/pr-manager.rst

So if we did want to change these files, we should stick with RST.

Regards,
Daniel

Eric Blake Sept. 4, 2018, 7:44 p.m. UTC | #2

On 09/02/2018 12:53 PM, Yoni Bettan wrote:
> This patch make INFO files (e.g. README, CODING_STYLE and HACKING) much more
> readable when watched from GitHub GUI.
> 
> ./VERSION, ./MAINTAINERS were leave untouched otherwise
> ./scripts/get_maintainer.pl breaks.
> 
> ./COPYING, ./LICENSE ./COPYING.LIB were leave untouched because it look likes
> they come from GNU and not QEMU.
> 
> Visualization of the change can be found at
> https://github.com/ybettan/qemu/tree/md.
> NOTE:
> This last part of the message should be removed from the commit message
> since I will remove the 'md' branch from my fork if the patch is
> accepted.

I'm a bit late to the thread, but wanted to point out this tangent:

Note that the cover letter is not committed into git, so a disclaimer 
about removing the last paragraph of the cover letter is pointless.

Had this been an actual commit message, it's best to stick such 
disclaimers (which are useful to reviewers, but not to long-term git 
log) after the --- that separates the actual commit message from the 
patch (as 'git am' will automatically strip such disclaimers when a 
maintainer takes in your patch for merging through their tree).