[PULL,0/4] Docs patches
mbox

Message ID 20190905134526.32146-1-berrange@redhat.com
State New
Headers show

Pull-request

https://github.com/berrange/qemu tags/docs-pull-request

Message

Daniel P. Berrangé Sept. 5, 2019, 1:45 p.m. UTC
The following changes since commit 500efcfcf0fe2e0dae1d25637a13435ce7b6e421:

  Merge remote-tracking branch 'remotes/rth/tags/pull-or1k-20190904' into staging (2019-09-05 09:33:01 +0100)

are available in the Git repository at:

  https://github.com/berrange/qemu tags/docs-pull-request

for you to fetch changes up to 9f8efa74d3f1cb9ceeee957ee382c2b4feb2ae30:

  docs: split the CODING_STYLE doc into distinct groups (2019-09-05 14:41:00 +0100)

----------------------------------------------------------------

* Merges HACKING into CODING_STYLE
* Converts README and CODING_STYLE docs into RST syntax
* Documents use of auto cleanup functions

----------------------------------------------------------------

Daniel P. Berrangé (4):
  docs: convert README, CODING_STYLE and HACKING to RST syntax
  docs: merge HACKING.rst contents into CODING_STYLE.rst
  docs: document use of automatic cleanup functions in glib
  docs: split the CODING_STYLE doc into distinct groups

 CODING_STYLE          | 216 --------------
 CODING_STYLE.rst      | 641 ++++++++++++++++++++++++++++++++++++++++++
 HACKING               | 257 -----------------
 README => README.rst  |  47 ++--
 scripts/checkpatch.pl |   2 +-
 5 files changed, 671 insertions(+), 492 deletions(-)
 delete mode 100644 CODING_STYLE
 create mode 100644 CODING_STYLE.rst
 delete mode 100644 HACKING
 rename README => README.rst (84%)

Comments

Peter Maydell Sept. 5, 2019, 3:34 p.m. UTC | #1
On Thu, 5 Sep 2019 at 14:45, Daniel P. Berrangé <berrange@redhat.com> wrote:
>
> The following changes since commit 500efcfcf0fe2e0dae1d25637a13435ce7b6e421:
>
>   Merge remote-tracking branch 'remotes/rth/tags/pull-or1k-20190904' into staging (2019-09-05 09:33:01 +0100)
>
> are available in the Git repository at:
>
>   https://github.com/berrange/qemu tags/docs-pull-request
>
> for you to fetch changes up to 9f8efa74d3f1cb9ceeee957ee382c2b4feb2ae30:
>
>   docs: split the CODING_STYLE doc into distinct groups (2019-09-05 14:41:00 +0100)
>
> ----------------------------------------------------------------
>
> * Merges HACKING into CODING_STYLE
> * Converts README and CODING_STYLE docs into RST syntax
> * Documents use of auto cleanup functions
>
> ----------------------------------------------------------------
>
> Daniel P. Berrangé (4):
>   docs: convert README, CODING_STYLE and HACKING to RST syntax
>   docs: merge HACKING.rst contents into CODING_STYLE.rst
>   docs: document use of automatic cleanup functions in glib
>   docs: split the CODING_STYLE doc into distinct groups
>
>  CODING_STYLE          | 216 --------------
>  CODING_STYLE.rst      | 641 ++++++++++++++++++++++++++++++++++++++++++
>  HACKING               | 257 -----------------
>  README => README.rst  |  47 ++--
>  scripts/checkpatch.pl |   2 +-

I'm going to apply this, but something I thought of looking at
the diffstat: should some or all of this be in the docs/devel
manual rather than free-floating rst files in the root directory?

thanks
-- PMM
Peter Maydell Sept. 5, 2019, 4:08 p.m. UTC | #2
On Thu, 5 Sep 2019 at 14:45, Daniel P. Berrangé <berrange@redhat.com> wrote:
>
> The following changes since commit 500efcfcf0fe2e0dae1d25637a13435ce7b6e421:
>
>   Merge remote-tracking branch 'remotes/rth/tags/pull-or1k-20190904' into staging (2019-09-05 09:33:01 +0100)
>
> are available in the Git repository at:
>
>   https://github.com/berrange/qemu tags/docs-pull-request
>
> for you to fetch changes up to 9f8efa74d3f1cb9ceeee957ee382c2b4feb2ae30:
>
>   docs: split the CODING_STYLE doc into distinct groups (2019-09-05 14:41:00 +0100)
>
> ----------------------------------------------------------------
>
> * Merges HACKING into CODING_STYLE
> * Converts README and CODING_STYLE docs into RST syntax
> * Documents use of auto cleanup functions
>
> ----------------------------------------------------------------


Applied, thanks.

Please update the changelog at https://wiki.qemu.org/ChangeLog/4.2
for any user-visible changes.

-- PMM
Daniel P. Berrangé Sept. 6, 2019, 9:24 a.m. UTC | #3
On Thu, Sep 05, 2019 at 04:34:33PM +0100, Peter Maydell wrote:
> On Thu, 5 Sep 2019 at 14:45, Daniel P. Berrangé <berrange@redhat.com> wrote:
> >
> > The following changes since commit 500efcfcf0fe2e0dae1d25637a13435ce7b6e421:
> >
> >   Merge remote-tracking branch 'remotes/rth/tags/pull-or1k-20190904' into staging (2019-09-05 09:33:01 +0100)
> >
> > are available in the Git repository at:
> >
> >   https://github.com/berrange/qemu tags/docs-pull-request
> >
> > for you to fetch changes up to 9f8efa74d3f1cb9ceeee957ee382c2b4feb2ae30:
> >
> >   docs: split the CODING_STYLE doc into distinct groups (2019-09-05 14:41:00 +0100)
> >
> > ----------------------------------------------------------------
> >
> > * Merges HACKING into CODING_STYLE
> > * Converts README and CODING_STYLE docs into RST syntax
> > * Documents use of auto cleanup functions
> >
> > ----------------------------------------------------------------
> >
> > Daniel P. Berrangé (4):
> >   docs: convert README, CODING_STYLE and HACKING to RST syntax
> >   docs: merge HACKING.rst contents into CODING_STYLE.rst
> >   docs: document use of automatic cleanup functions in glib
> >   docs: split the CODING_STYLE doc into distinct groups
> >
> >  CODING_STYLE          | 216 --------------
> >  CODING_STYLE.rst      | 641 ++++++++++++++++++++++++++++++++++++++++++
> >  HACKING               | 257 -----------------
> >  README => README.rst  |  47 ++--
> >  scripts/checkpatch.pl |   2 +-
> 
> I'm going to apply this, but something I thought of looking at
> the diffstat: should some or all of this be in the docs/devel
> manual rather than free-floating rst files in the root directory?

The answer really hinges on whether moving CODING_STYLE into the
docs/devel directory will make it less obvious to users.

On a related point, with the prevelance of github/gitlab for
hosting, it has become fairly common to have a top level
CONTRIBUTING.md file, with guidance of key factors relating
to contributing - how to submit patches, code of conduct,
developer signoff, coding style, etc. This file doesn't
have to contain the actual content - often people just use
it as an index to link to all the individual topic docs:

  https://github.com/rails/rails/blob/master/CONTRIBUTING.md
  https://github.com/atom/atom/blob/master/CONTRIBUTING.md
  https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md
  https://github.com/creativecommons/.github/blob/master/CONTRIBUTING.md

So we could just move CODING_STYLE into the docs/devel dir and link
to it from a CONTRIBUTING.md (well .rst) file.

Regards,
Daniel
Eric Blake Sept. 6, 2019, 1:13 p.m. UTC | #4
On 9/6/19 4:24 AM, Daniel P. Berrangé wrote:

>>
>> I'm going to apply this, but something I thought of looking at
>> the diffstat: should some or all of this be in the docs/devel
>> manual rather than free-floating rst files in the root directory?
> 
> The answer really hinges on whether moving CODING_STYLE into the
> docs/devel directory will make it less obvious to users.

A git symlink would allow us to keep the file at the top level (for easy
location while browsing the repository) as well as under docs (for easy
incorporation into the doc build recipes).  I don't know if tooling
would require the original in one place (forcing the other to be the
link), or if you can do it in either direction.

> 
> So we could just move CODING_STYLE into the docs/devel dir and link
> to it from a CONTRIBUTING.md (well .rst) file.

A textual link in an actual file is slightly different than a git
symlink, but yes, that would probably also work (even if it requires
chasing through one more layer of files).