Merge pull request #5476 from garlick/user_docs

docs: add build instructions and support info

doc/Makefile.am

@@ -394,6 +394,9 @@ EXTRA_DIST = \
 	domainrefs.py \
 	index.rst \
 	index_man.rst \
+	build.rst \
+	support.rst \
+	images/lgplv3-147x51.png \
 	$(RST_FILES) \
 	man1/index.rst \
 	man1/index_general.rst \

doc/build.rst

@@ -0,0 +1,130 @@
+Building Releases
+=================
+
+Version Numbering
+-----------------
+
+Flux-core releases are numbered with
+`Semantic Versioning <https://semver.org/>`_, where MAJOR.MINOR.PATCH release
+numbers communicate that:
+
+- major releases may break API
+
+- minor releases add functionality in a backward compatible manner
+
+- patch releases make backward compatible bug fixes
+
+At this time, the project is at major version zero, indicating interfaces
+are not yet stable.  That said, flux-core developers try to minimize
+disruption to early adopters and announce any necessary breaking changes
+in the release notes.
+
+Obtaining Releases
+------------------
+
+Tarballs and release notes are available on the
+`Github releases page <https://github.com/flux-framework/flux-core/releases>`_.
+
+Releases for all Flux framework projects are also announced on the
+`Flux Framework releases page <https://flux-framework.org/releases/>`_.
+
+Installing Dependencies
+-----------------------
+
+Several external software packages are prerequisites for building Flux.
+Scripts that install these packages for debian and redhat based distros are
+located in the flux-core source tree ``scripts`` sub-directory.
+
+The following packages are optional and may be omitted if you do not require
+the associated functionality:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Package
+     - Functionality
+
+   * - `flux-security <https://github.com/flux-framework/flux-security>`_
+     - Launching work as multiple users.
+
+       For example when Flux is to be the native resource manager on a cluster.
+
+   * - Sphinx
+     - Building man pages and documentation
+
+   * - MPI
+     - Test only: sanity tests that Flux can launch MPI programs
+
+   * - valgrind
+     - Test only: checks for memory errors
+
+Configuring and Building a Release
+----------------------------------
+
+flux-core uses GNU autotools internally, so it supports the usual
+`Use Cases for the GNU Build System <https://www.gnu.org/software/automake/manual/html_node/Use-Cases.html>`_.  A standard build follows this pattern:
+
+.. code-block:: console
+
+  $ tar xzf flux-core-X.Y.Z.tar.gz
+  $ cd flux-core-X.Y.Z
+  $ ./configure --with-flux-security
+  $ make
+  $ make check
+  $ make install
+
+Configure *should* abort if any required build dependencies are missing or
+insufficient.  Configure options options may be listed with ``./configure
+--help``.
+
+``make -j N`` may be used to speed up the build and check targets by
+increasing parallelism.
+
+All checks are expected to pass, although some timing related test defects
+may cause tests to sporadically fail on slow systems or when run with too much
+parallelism.  ``make recheck`` re-runs any failing checks.
+
+Packages
+--------
+
+RPM packages for TOSS 4 (RHEL 8 based) are produced by the TOSS build system
+and can be made available externally on request.  When requested, these are
+manually added to the release assets on github.
+
+deb packages for Debian or Ubuntu can be built from a release tarball with
+``make deb``, producing debs in the ``debbuild`` sub-directory.  This target
+is used by some Flux team members to build packages for test clusters running
+the `Raspberry Pi OS <https://www.raspberrypi.com/software/>`_ (Debian/GNU 11).
+
+Docker Images
+-------------
+
+Docker images for tagged releases as well as a current development snapshot
+are available in the `fluxrm/flux-core Dockerhub
+<https://hub.docker.com/r/fluxrm/flux-core/tags>`_.  For example, the following
+downloads a debian bookworm image containing flux-core 0.54.0 and starts a
+flux instance within it:
+
+.. code-block:: console
+
+  $ docker pull fluxrm/flux-core:bookworm-v0.54.0-amd64
+  $ docker run -ti fluxrm/flux-core:bookworm-v0.54.0-amd64
+  ƒ(s=1,d=0) fluxuser@080d84548cc4:~$
+
+Spack
+-----
+
+Flux-core and its dependencies can also be built using `spack
+<https://spack-tutorial.readthedocs.io/en/latest/>`_, for example:
+
+.. code-block:: console
+
+  $ git clone --depth=100 https://github.com/spack/spack.git
+  $ cd spack
+  $ . share/spack/setup-env.sh
+  $ spack install [email protected] %[email protected]
+  $ spack find flux-core
+  -- linux-ubuntu22.04-zen2 / [email protected] --------------------------
+  [email protected]
+  ==> 1 installed package
+  $ spack load flux-core

doc/index.rst

@@ -97,5 +97,7 @@ Table of Contents
 .. toctree::
    :maxdepth: 2
 
+   build
+   support
    index_man
    python/index

doc/support.rst

@@ -0,0 +1,57 @@
+License and Support
+===================
+
+License
+-------
+
+.. figure:: images/lgplv3-147x51.png
+   :alt: LGPL-3.0 logo
+   :align: right
+
+Flux-core is licensed under `LGPL-3.0
+<https://www.gnu.org/licenses/lgpl-3.0.en.html>`_ which means project forks
+must retain the same license and follow the license's requirements for making
+source code available to end users.
+
+Software that merely uses flux-core's APIs may be independently licensed.
+
+Support
+-------
+
+All flux-core issues and changes are proposed and discussed on `Github
+<https://github.com/flux-framework/flux-core>`_.  The team values
+openness and inclusivity and encourages collaboration.  Engage with us!
+
+If you have a problem that might be a flux-core bug, please first search
+existing issues, then open a new `Github issue
+<https://github.com/flux-framework/flux-core/issues>`_ if necessary.
+Be sure to include relevant context and especially the flux version that
+is exhibiting the problem:
+
+.. code-block:: console
+
+  $ flux version
+  commands:    		0.54.0
+  libflux-core:		0.54.0
+  libflux-security:	0.10.0
+  build-options:	+systemd+hwloc==2.4.0+zmq==4.3.4
+
+`Github discussions <https://github.com/flux-framework/flux-core/discussions>`_
+are sometimes useful too.
+
+Development Commitment
+----------------------
+
+At this time, Lawrence Livermore National Laboratory (LLNL) has a team of
+four full time employees working on flux-core, and several additional employees
+and collaborators working on the broader Flux Framework and related research
+areas.  LLNL is committed to making Flux a production quality tool for HPC
+workload management, and has sustained its investment for over a decade thus
+far.
+
+Flux is part of the `TOSS <https://hpc.llnl.gov/documentation/toss>`_
+operating system and thus is supported across multiple U.S. national laboratory
+facilities.
+
+The Flux team welcomes all users and contributors to the Flux community and
+will do its best enable the community to grow and thrive.

doc/test/spell.en.pws

@@ -718,3 +718,23 @@ MemoryMax
 MemoryLow
 MemoryMin
 myattr
+autotools
+cd
+debbuild
+debian
+distros
+dockerhub
+fluxrm
+LLNL
+redhat
+RHEL
+spack
+ubuntu
+xzf
+APIs
+HPC
+infinitum
+OpenMPI
+inclusivity
+lgplv
+png

doc/test/spellcheck

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 if test $man_base_dir; then
-    set ${man_base_dir}/man*/*.rst ${man_base_dir}/man*/common/*.rst
+    set ${man_base_dir}/*.rst ${man_base_dir}/man*/*.rst ${man_base_dir}/man*/common/*.rst
 fi
 
 if test $# == 0; then