Re: [Qemu-devel] [PULL 0/4] Docs patches
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). -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org signature.asc Description: OpenPGP digital signature
Re: [Qemu-devel] [PULL 0/4] Docs patches
On Thu, Sep 05, 2019 at 04:34:33PM +0100, Peter Maydell wrote: > On Thu, 5 Sep 2019 at 14:45, Daniel P. Berrangé 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 9f8efa74d3f1cb9c957ee382c2b4feb2ae30: > > > > 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 -- |: https://berrange.com -o-https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o-https://fstop138.berrange.com :| |: https://entangle-photo.org-o-https://www.instagram.com/dberrange :|
Re: [Qemu-devel] [PULL 0/4] Docs patches
On Thu, 5 Sep 2019 at 14:45, Daniel P. Berrangé 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 9f8efa74d3f1cb9c957ee382c2b4feb2ae30: > > 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
Re: [Qemu-devel] [PULL 0/4] Docs patches
On Thu, 5 Sep 2019 at 14:45, Daniel P. Berrangé 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 9f8efa74d3f1cb9c957ee382c2b4feb2ae30: > > 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
