Merge pull request #914 from vojtechtrefny/master_readmes-update

README update

Makefile.am

@@ -62,7 +62,7 @@ if WITH_GTK_DOC
 SUBDIRS += docs
 endif
 
-dist_noinst_DATA = features.rst specs.rst LICENSE tests
+dist_noinst_DATA = LICENSE tests
 
 MAINTAINERCLEANFILES = Makefile.in aclocal.m4 config.guess config.sub \
     configure depcomp install-sh ltmain.sh missing py-compile compile ar-lib \

README.DEVEL.rst → README.DEVEL.md

@@ -21,6 +21,15 @@ multiple implementations for plugins (if that's the case). As was already
 mentioned above, the library is just a thin wrapper so there's no point in
 trying to bypass it and use the plugins directly as standalone libraries.
 
+Coding style
+-------------
+
+ - Please follow the coding style already used.
+ - Spaces, not tabs, are used (except for Makefiles).
+
+Language bindings
+------------------
+
 Though the library uses the so called *GObject introspection* (*GI*) framework
 to provide bindings for languages other than *C*, it's not an object-oriented
 library and it makes little to no use of the *GObject* type system. The only
@@ -40,6 +49,9 @@ these stubs are replaced by the real functions provided by the plugins. The
 helper script also generates functions used for loading plugins (all their
 functions have to be loaded one by one).
 
+Adding a new function
+----------------------
+
 Thus if a new function is being added to any of the plugins:
 
 1. the definition of the function has to be added to the particular ``.api``
@@ -54,6 +66,8 @@ Thus if a new function is being added to any of the plugins:
 5. the function has to be added to the particular place in the documentation
    (the ``docs/libblockdev-sections.txt`` file)
 
+Adding a new plugin
+--------------------
 
 If a new plugin is being added:
 
@@ -74,9 +88,12 @@ If a new struct field is being added, it has to be added to the end of the
 structure so that original fields stay in their places from the ABI point of
 view.
 
+Directory structure
+--------------------
 
-The directory structure is as follows::
+The directory structure is as follows:
 
+```
   libblockdev
   ├── data                     -- data files
   │   └── conf.d               -- configuration files
@@ -94,3 +111,67 @@ The directory structure is as follows::
   │   └── utils                -- sources of the utility library
   ├── tests                    -- tests
   └── tools                    -- sources of various nice tools
+```
+
+Making releases
+================
+
+ - [ ] ``sudo git clean -xdf``
+
+ - [ ] ``./autogen.sh && ./configure``
+
+ - [ ] ``make bumpver``
+
+ - [ ] Add a new entry to the *NEWS.rst* file (full list of changes should be
+       generated with ``make shortlog``).
+
+ - [ ] Commit all the changes as *New version - $VERSION*.
+
+ - [ ] ``make release`` (requires a GPG key to sign the tag)
+
+ - [ ] ``git push && git push --tags``
+
+ - [ ] Edit the new release (for the new tag) at GitHub and:
+
+   - [ ] add some detailed information about it (from the *NEWS.rst*) file to it,
+
+   - [ ] upload the tarball created above (``make release``) to the release.
+
+ - [ ] Generate documentation for the Python bindings as described below and copy
+       it to *docs/html*
+
+ - [ ] Update the documentation by rsyncing the contents of the *docs/html*
+       folder elsewhere, switching to the *gh-pages* branch, rsyncing the
+       contents back and committing it as an update of the docs for the new
+       release.
+
+Generating Python bindings documentation
+-----------------------------------------
+
+ Documentation for Python bindings is generated using [pgi-docgen](https://github.com/pygobject/pgi-docgen). This unfortunately works only on Debian so we are using a custom Docker image to build the documentation:
+
+1. Go to the *misc* directory.
+1. Build new image using the provided *Dockerfile*
+
+      `$ buildah bud --tag debian-docs-builder -f PythonDocs.Dockerfile .`
+
+      This will create a new Debian Testing based image and build the documentation in it from latest libblockdev.
+1. Create container from the created image
+
+      `$ buildah from localhost/debian-docs-builder`
+1. Mount the container
+
+      `$ buildah unshare`
+
+      `# mnt=$(buildah mount debian-docs-builder-working-container)`
+
+1. Copy generated documentation from the container to *docs/html*
+
+      `# cp -R $mnt/root/pgi-docgen/_docs/_build/BlockDev-2.0 <path_to_libblockdev>/docs/html`
+
+      `# cp -R $mnt/root/pgi-docgen/_docs/_build/_static <path_to_libblockdev>/docs/html`
+
+1. Manually fix few issues in the *BlockDev-2.0/index.html*
+
+      - Fix version of libblockdev (pgi-docgen can't detect it so it uses version from Debian package).
+      - Remove link to dependencies (we are not copying documentation generated for GLib and GObject because it more than 100 MB).

README.md

@@ -2,29 +2,78 @@
 
 <img alt="CI status" src="https://fedorapeople.org/groups/storage_apis/statuses/libblockdev-master.svg" width="100%" height="350ex" />
 
-
 ### Introduction
 
 libblockdev is a C library supporting GObject introspection for manipulation of
 block devices. It has a plugin-based architecture where each technology (like
 LVM, Btrfs, MD RAID, Swap,...) is implemented in a separate plugin, possibly
 with multiple implementations (e.g. using LVM CLI or the new LVM DBus API).
 
-For more information about the library's architecture see the specs.rst
-file. For more information about the expected functionality and features see the
-features.rst file.
+#### Features
+
+Following storage technologies are supported by libblockdev
+
+ - partitions
+   - MSDOS, GPT
+ - filesystem operations
+   - ext2, ext3, ext4, xfs, vfat, ntfs, exfat, btrfs, f2fs, nilfs2, udf
+   - mounting
+ - LVM
+   - thin provisioning, LVM RAID, cache, LVM VDO
+ - BTRFS
+   - multi-device volumes, subvolumes, snapshots
+ - swap
+ - encryption
+   - LUKS, TrueCrypt/VeraCrypt, BitLocker, FileVault2
+   - integrity
+ - DM (device mapper)
+ - loop devices
+ - MD RAID
+ - multipath
+ - s390
+   - DASD, zFCP
+ - NVDIMM namespaces
+ - NVMe
+
+#### Architecture
+
+The library itself is only a thin wrapper around a set of plugins, each for a
+particular technology listed above. The library provides an API consisting of
+sets of functions provided by its plugins. For example, there is a
+symbol/function called ``bd_lvm_lvcreate`` provided by the library which is
+dynamically loaded from the LVM plugin when the library's ``bd_init`` function
+will be called. Initially all those functions are no-ops just printing a warning
+on stderr and doing nothing. This way applications using the library won't
+crash, the operations just won't be run. Of course, the library
+has ``bd_is_plugin_available``, which allows applications to check if something
+is provided/implemented or not.
+
+#### Technologies behind the library
+
+The library is written in C using the GLib library. The GLib library provides a
+lot of handy utilities that may be used by the library (no need for a new
+implementation of hash tables, lists, etc.) and moreover, it should be really
+easy to create bindings for the library via GObject introspection that works
+even with "not OOP" code. However, instead of returning links to structs
+(e.g. as a return value of the ``bd_lvm_vginfo`` function) it will return
+references to GObjects with attributes/properties and access methods. The reason
+is again an easy way to create bindings which we get for free.
+
+### License
+
+The libblockdev code is licensed under LGPL 2.1 or later, see [LICENSE](LICENSE)
+for full text of the license.
+
+### Development
 
-For information about development and contributing guidelines see the
-README.DEVEL.rst file.
+For developer documentation see [README.DEVEL.md](README.DEVEL.md).
 
-For more information about the API see the generated documentation at
-http://storaged.org/libblockdev/.
+API documentation is available at [https://storaged.org/libblockdev](https://storaged.org/libblockdev).
 
+#### Branches and supported versions
 
-### Branches and API stability
+The currently actively developed and supported version is 3.x on the *main* branch.
+New features should target this release.
 
-We are currently working on a new major release 3.0 which will also include major API
-overhaul, some backward-incompatible changes are already present on the *master* branch
-and we do not recommend using it right now if you are not interested in libblockdev
-development. Stable *2.x-branch* is still supported and we will continue to backport
-bugfixes and selected new features to it from *master*.
+The older 2.x version available on the *2.x-branch* is still supported but new features
+are not planned for this release.

dist/libblockdev.spec.in

@@ -641,7 +641,6 @@ find %{buildroot} -type f -name "*.la" | xargs %{__rm}
 %config %{_sysconfdir}/libblockdev/conf.d/00-default.cfg
 
 %files devel
-%doc features.rst specs.rst
 %{_libdir}/libblockdev.so
 %dir %{_includedir}/blockdev
 %{_includedir}/blockdev/blockdev.h