The information contained in README is either redundant or already covered by the package metadata, so it's pointless to include this file. Similarly, HACKING only makes sense as a companion to the source code, and can thus be left out of the binary package. Signed-off-by: Andrea Bolognani <abologna(a)redhat.com&gt; --- libvirt-dbus.spec.in | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libvirt-dbus.spec.in b/libvirt-dbus.spec.in index 3425e9e..4be17f2 100644 --- a/libvirt-dbus.spec.in +++ b/libvirt-dbus.spec.in @@ -50,7 +50,7 @@ getent passwd %{system_user} >/dev/null || \ exit 0 %files -%doc README.md HACKING.md AUTHORS NEWS +%doc AUTHORS NEWS %license COPYING %{_sbindir}/libvirt-dbus %{_datadir}/dbus-1/services/org.libvirt.service -- 2.25.3

Signed-off-by: Andrea Bolognani <abologna(a)redhat.com&gt; --- HACKING.md | 205 --------------------------------------------------- HACKING.rst | 207 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 207 insertions(+), 205 deletions(-) delete mode 100644 HACKING.md create mode 100644 HACKING.rst diff --git a/HACKING.md b/HACKING.md deleted file mode 100644 index e90f136..0000000 --- a/HACKING.md +++ /dev/null @@ -1,205 +0,0 @@ -Tips for hacking on libvirt-dbus -================================ - -Here is where to get code: - -``` -$ git clone https://libvirt.org/git/libvirt-dbus.git -``` - -Alternatively you can use one of the mirrors: - -[https://github.com/libvirt/libvirt-dbus](https://github.com/libvirt/libvirt-dbus) -[https://gitlab.com/libvirt/libvirt-dbus](https://gitlab.com/libvirt/libvirt-dbus) - - -Running from git repository ---------------------------- - - * The first step is to run meson to create build directory: - - ``` - meson build - ``` - - Now you can compile libvirt-dbus: - - ``` - ninja -C build - ``` - - - * Before posting a patch, you should run tests: - - ``` - ninja -C build test - ``` - - The test tool requires python3, python3-pytest, python3-dbus and flake8. - - It is possible to run only specific test using: - - ``` - meson test -C build $test-name - ``` - - or a group of tests: - - ``` - meson test -C build --suite $label - ``` - - For more information see [https://mesonbuild.com/Unit-tests.html#testing-tool](https://mesonbuild.c.... - - - * To run libvirt-dbus directly from the build dir without installing it - use the run script: - - ``` - ./run ./src/libvirt-dbus - ``` - - -Coding style rules ------------------- - - * Opening & closing braces for functions should be at start of line: - - ``` - int - foo(int bar) - { - ... - } - ``` - - Not - - ``` - int - foo(int bar) { - ... - } - ``` - - * Opening brace for if/while/for loops should be at the end of line: - - ``` - if (foo) { - bar; - wizz; - } - ``` - - Not - - ``` - if (foo) - { - bar; - wizz; - } - ``` - - Rationale: putting every if/while/for opening brace on a new line - expands function length too much. - - - * If a brace needs to be used for one clause in an if/else statement, - it should be used for both clauses, even if the other clauses are - only single statements. eg: - - ``` - if (foo) { - bar; - wizz; - } else { - eek; - } - ``` - - Not - - ``` - if (foo) { - bar; - wizz; - } else - eek; - ``` - - - * Function parameter attribute annotations should follow the parameter - name, eg: - - ``` - int - foo(int bar G_GNUC_UNUSED) - { - } - ``` - - Not - - ``` - int - foo(G_GNUC_UNUSED int bar) - { - } - ``` - - Rationale: Adding / removing G_GNUC_UNUSED should not cause the - rest of the line to move around since that obscures diffs. - - - * There should be no space between function names & open brackets eg: - - ``` - int - foo(int bar) - { - } - ``` - - Not - - ``` - int - foo (int bar) - { - } - ``` - - - * To keep lines under 80 characters (where practical), multiple parameters - should be on new lines. Do not attempt to line up parameters vertically eg: - - ``` - int - foo(int bar, - unsigned long wizz) - { - } - ``` - - Not - - ``` - int - foo(int bar, unsigned long wizz) - { - } - ``` - - Not - - ``` - int - foo(int bar, - unsigned long wizz) - { - } - ``` - - Rationale: attempting vertical alignment causes bigger diffs when - modifying code if type names change causing whitespace re-alignment. diff --git a/HACKING.rst b/HACKING.rst new file mode 100644 index 0000000..6f2bca1 --- /dev/null +++ b/HACKING.rst @@ -0,0 +1,207 @@ +================================ +Tips for hacking on libvirt-dbus +================================ + +Here is where to get code: + +:: + + $ git clone https://libvirt.org/git/libvirt-dbus.git + +Alternatively you can use one of the mirrors: + +https://github.com/libvirt/libvirt-dbus +https://gitlab.com/libvirt/libvirt-dbus + + +Running from git repository +=========================== + +* The first step is to run meson to create build directory: + + :: + + meson build + + Now you can compile libvirt-dbus: + + :: + + ninja -C build + + +* Before posting a patch, you should run tests: + + :: + + ninja -C build test + + The test tool requires python3, python3-pytest, python3-dbus and flake8. + + It is possible to run only specific test using: + + :: + + meson test -C build $test-name + + or a group of tests: + + :: + + meson test -C build --suite $label + + For more information see https://mesonbuild.com/Unit-tests.html#testing-tool. + + +* To run libvirt-dbus directly from the build dir without installing it + use the run script: + + :: + + ./run ./src/libvirt-dbus + + +Coding style rules +================== + +* Opening & closing braces for functions should be at start of line: + + :: + + int + foo(int bar) + { + ... + } + + Not + + :: + + int + foo(int bar) { + ... + } + + +* Opening brace for if/while/for loops should be at the end of line: + + :: + + if (foo) { + bar; + wizz; + } + + Not + + :: + + if (foo) + { + bar; + wizz; + } + + Rationale: putting every if/while/for opening brace on a new line + expands function length too much. + + +* If a brace needs to be used for one clause in an if/else statement, + it should be used for both clauses, even if the other clauses are + only single statements. eg: + + :: + + if (foo) { + bar; + wizz; + } else { + eek; + } + + Not + + :: + + if (foo) { + bar; + wizz; + } else + eek; + + +* Function parameter attribute annotations should follow the parameter + name, eg: + + :: + + int + foo(int bar G_GNUC_UNUSED) + { + } + + Not + + :: + + int + foo(G_GNUC_UNUSED int bar) + { + } + + Rationale: Adding / removing G_GNUC_UNUSED should not cause the + rest of the line to move around since that obscures diffs. + + +* There should be no space between function names & open brackets eg: + + :: + + int + foo(int bar) + { + } + + Not + + :: + + int + foo (int bar) + { + } + + +* To keep lines under 80 characters (where practical), multiple parameters + should be on new lines. Do not attempt to line up parameters vertically eg: + + :: + + int + foo(int bar, + unsigned long wizz) + { + } + + Not + + :: + + int + foo(int bar, unsigned long wizz) + { + } + + Not + + :: + + int + foo(int bar, + unsigned long wizz) + { + } + + Rationale: attempting vertical alignment causes bigger diffs when + modifying code if type names change causing whitespace re-alignment. -- 2.25.3

Like NEWS, this was very close to being a valid Markdown document before, and now it's a valid reStructuredText one. Signed-off-by: Andrea Bolognani <abologna(a)redhat.com&gt; --- AUTHORS.in | 16 ---------------- AUTHORS.rst.in | 17 +++++++++++++++++ libvirt-dbus.spec.in | 2 +- meson.build | 6 +++--- tools/gen-authors.sh | 2 +- 5 files changed, 22 insertions(+), 21 deletions(-) delete mode 100644 AUTHORS.in create mode 100644 AUTHORS.rst.in diff --git a/AUTHORS.in b/AUTHORS.in deleted file mode 100644 index d5a486e..0000000 --- a/AUTHORS.in +++ /dev/null @@ -1,16 +0,0 @@ - libvirt-dbus Authors - ==================== - -The libvirt-dbus project was started by: - - Lars Karlitski <lars(a)karlitski.net&gt; - Pavel Hrdina <phrdina(a)redhat.com&gt; - -The primary maintainers of libvirt-dbus are: - - Katerina Koukiou <kkoukiou(a)redhat.com&gt; - Pavel Hrdina <phrdina(a)redhat.com&gt; - -Patches have been received from: - -@contributorslist@ diff --git a/AUTHORS.rst.in b/AUTHORS.rst.in new file mode 100644 index 0000000..1087b73 --- /dev/null +++ b/AUTHORS.rst.in @@ -0,0 +1,17 @@ +==================== +libvirt-dbus Authors +==================== + +The libvirt-dbus project was started by: + +* Lars Karlitski <lars(a)karlitski.net&gt; +* Pavel Hrdina <phrdina(a)redhat.com&gt; + +The primary maintainers of libvirt-dbus are: + +* Katerina Koukiou <kkoukiou(a)redhat.com&gt; +* Pavel Hrdina <phrdina(a)redhat.com&gt; + +Patches have been received from: + +@contributorslist@ diff --git a/libvirt-dbus.spec.in b/libvirt-dbus.spec.in index a9fdd0c..175910e 100644 --- a/libvirt-dbus.spec.in +++ b/libvirt-dbus.spec.in @@ -50,7 +50,7 @@ getent passwd %{system_user} >/dev/null || \ exit 0 %files -%doc AUTHORS NEWS.rst +%doc AUTHORS.rst NEWS.rst %license COPYING %{_sbindir}/libvirt-dbus %{_datadir}/dbus-1/services/org.libvirt.service diff --git a/meson.build b/meson.build index b293b8c..7518e94 100644 --- a/meson.build +++ b/meson.build @@ -256,11 +256,11 @@ if git authors = run_command('tools/gen-authors.sh') configure_file( configuration: { 'contributorslist': authors.stdout() }, - input: 'AUTHORS.in', - output: 'AUTHORS', + input: 'AUTHORS.rst.in', + output: 'AUTHORS.rst', ) - foreach file : [ 'libvirt-dbus.spec', 'AUTHORS' ] + foreach file : [ 'libvirt-dbus.spec', 'AUTHORS.rst' ] meson.add_dist_script('tools/dist.sh', meson.build_root(), file) endforeach endif diff --git a/tools/gen-authors.sh b/tools/gen-authors.sh index eb39215..bf0a3b6 100755 --- a/tools/gen-authors.sh +++ b/tools/gen-authors.sh @@ -1,4 +1,4 @@ #!/bin/sh cd $MESON_SOURCE_ROOT -git log --pretty=format:' %aN <%aE>' | sort -u +git log --pretty=format:'* %aN <%aE>' | sort -u -- 2.25.3

On Sat, Apr 25, 2020 at 10:59:44PM +0200, Andrea Bolognani wrote: This broke on RHEL-7 CI since it needs a -3 suffix, and IIRC will break other distros which need a .py suffix In libvirt configure.ac we pick from rst2man rst2man.py rst2man-3 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 :|

People who install the RPM packages already get this, but it's good practice so let's make it happen for those who install from source as well. The process is straightforward, but we have to be a bit careful with AUTHORS because this specific file is found in different directories depending on whether we're building from git or from a release. Signed-off-by: Andrea Bolognani <abologna(a)redhat.com&gt; --- meson.build | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/meson.build b/meson.build index 7518e94..9395bc4 100644 --- a/meson.build +++ b/meson.build @@ -12,6 +12,7 @@ project( prefix = get_option('prefix') datadir = prefix / get_option('datadir') sbindir = prefix / get_option('sbindir') +set_variable('docdir', datadir / 'doc/libvirt-dbus') opt_dirs = [ 'dbus_interfaces', @@ -258,6 +259,7 @@ if git configuration: { 'contributorslist': authors.stdout() }, input: 'AUTHORS.rst.in', output: 'AUTHORS.rst', + install_dir: docdir, ) foreach file : [ 'libvirt-dbus.spec', 'AUTHORS.rst' ] @@ -266,6 +268,22 @@ if git endif +# Install documentation + +docs = [ + 'COPYING', + 'NEWS.rst', +] +if not git + docs += ['AUTHORS.rst'] +endif + +install_data( + docs, + install_dir: docdir, +) + + # Include sub-directories subdir('data') -- 2.25.3

On Sat, Apr 25, 2020 at 10:59:45PM +0200, Andrea Bolognani wrote: Do we really want this ? I've not noticed apps doing this in general - these files are usually non-installed with autotools and meson AFAIK. 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 :|

Now that the documentation is installed just like other files, we can also pick it from the installation directory instead of the source directory. Signed-off-by: Andrea Bolognani <abologna(a)redhat.com&gt; --- libvirt-dbus.spec.in | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/libvirt-dbus.spec.in b/libvirt-dbus.spec.in index 84172fa..2230ffc 100644 --- a/libvirt-dbus.spec.in +++ b/libvirt-dbus.spec.in @@ -50,8 +50,9 @@ getent passwd %{system_user} >/dev/null || \ exit 0 %files -%doc AUTHORS.rst NEWS.rst -%license COPYING +%doc %{_docdir}/%{name}/AUTHORS.rst +%doc %{_docdir}/%{name}/NEWS.rst +%license %{_docdir}/%{name}/COPYING %{_sbindir}/libvirt-dbus %{_datadir}/dbus-1/services/org.libvirt.service %{_datadir}/dbus-1/system-services/org.libvirt.service -- 2.25.3