# fedmod modularity tools

fedmod provides tools for working with Fedora's modulemd metadata format
that aren't related to actually building them (for build commands, see
fedpkg and mbs-build).

Currently, this consists of:

* `fedmod <query-command>`: simple repoquery-like commands providing operations
  like listing modules, resolving dependencies for packages, finding out
  where a certain package is, etc. See the
  [user docs](https://pagure.io/modularity/fedmod/blob/master/f/src/README.md)
  for a full list of available query subcommands.
* `fedmod rpm2module`: generates a draft modulemd file based on
  the given RPM name (multiple RPM names can be given, but the resulting
  draft module will lack any descriptive metadata in that case)
* `fedmod fetch-metadata`: download the F28 package and module metadata needed
  to generate draft module definitions (the metadata sets to use are not yet
  configurable)

## Project status

`fedmod` is not yet available from the main Fedora repos, but can be installed
from [COPR](https://copr.fedorainfracloud.org/coprs/g/modularity/fedmod/)
as follows:

    $ sudo dnf copr enable @modularity/fedmod
    $ sudo dnf install fedmod
    $ fedmod fetch-metadata
    $ fedmod rpm2module graphite-web

This will generate a draft `modulemd` file for Fedora's `graphite-web`
package on stdout.

See the local development instructions below for info on running directly
from a local development clone with `pipenv`.

## User documentation

Please see the [User docs of fedmod modularity tools](https://pagure.io/modularity/fedmod/blob/master/f/src/README.md).


## Local development

### Runtime dependencies

The preferred dependency management tool for development is `pipenv`:

    $ pipenv --three --site-packages
    $ PIP_IGNORE_INSTALLED=1 pipenv install --dev

The `PIP_IGNORE_INSTALLED=1` setting means that everything available to `pip`
will be installed into the virtual environment based on `Pipfile.lock`, and only
components that aren't installable with `pip` will be used from the system
Python installation.

Some dependencies aren't currently available from PyPI, and hence need to be
installed system-wide:

    $ sudo dnf install libmodulemd python3-gobject-base python3-solv

### Additional development dependencies

`pipenv` itself isn't packaged for Fedora yet, so the recommended bootstrapping
approach is to use the "pip script installer", `pipsi`:

    $ sudo dnf install pipsi
    $ pipsi install pew
    $ pipsi install pipenv

This will create a pair of isolated virtual environments in your home directory
specifically for `pipenv` and the tool it uses for virtual environment
management, `pew`. These can later be updated to newer versions using `pipsi`:

    $ pipsi upgrade pew
    $ pipsi upgrade pipenv

(Note: the `pipsi list` command will list all packages installed via `pipsi`,
and the commands they provide)

### Running the development version

After setting up the `pipenv` environment, the development version can be
run as follows

    $ pipenv run fedmod fetch-metadata
    $ pipenv run fedmod rpm2module graphite-web

Alternatively, start an interactive shell as described below for running the
tests, and `fedmod` will refer to the development version.

### Running the tests

After going through the environment setup steps above, start a shell that's
correctly configured to run the tests with `fedmod` and all of its
dependencies available:

    $ pipenv shell

The metadata needed by the module generator tests can then be installed with
`fedmod` itself:

    $ fedmod fetch-metadata

The tests can then be run in the launched subshell with:

    $ pytest tests

To test the package build process, tox is also supported:

    $ tox -e py36


### Reviewing project dependencies

To see the Python level dependencies graph:

    $ pew toggleglobalsitepackages
    $ pipenv graph
    $ pew toggleglobalsitepackages

(If you don't turn off global site-packages access first, you'll get the
dependency graph of all the installed system Python components as well)


### Testing Fedora system package compatibility

While the default development environment is managed with `pipenv` for a more
consistent cross-platform development experience, `fedmod` is intended to
support installation as a system package in Fedora 26 and later.

A specific tox environment is provided to enable this testing:

    $ tox -e system

The only component this installs into the environment is `fedmod` itself: all
other dependencies must be available as Python 3 system packages.

Unlike the regular test environment, this environment also implicitly runs
`fedmod fetch-metadata` in order to ensure that the metadata fetching operation
also works correctly given only system packages as dependencies.

## Publishing new releases

### COPR releases

The main current release mechanism is through COPR at
https://copr.fedorainfracloud.org/coprs/g/modularity/fedmod/.

This is configured to automatically build a new release every time a new tag
is pushed to the `fedmod` git repository.

`fedmod`'s RPMs are built with `tito`, but version tagging is handled with a
helper script. To publish a new release, run:

    $ ./tag-release.sh <X.Y.Z>
    $ git push && git push --tags


### PyPI releases

`fedmod` is also published to PyPI here: https://pypi.org/project/fedmod/

After releasing to COPR to ensure everything is properly tagged, a new PyPI
release can be made by doing:

    $ cd src
    $ rm dist/*
    $ python setup.py sdist bdist_wheel
    $ twine upload dist/*

The `dnf` and `solv` dependencies unfortunately mean the PyPI release isn't
particularly useful at this point (`pipsi` doesn't allow system level
dependencies, and even if it did, platforms that provide these libraries are
also likely to provide access to COPR).