howfairis

Command line tool to analyze a GitHub or GitLab repository's compliance with the fair-software.eu recommendations

https://github.com/fair-software/howfairis

Keywords

Keywords from Contributors

Repository

Command line tool to analyze a GitHub or GitLab repository's compliance with the fair-software.eu recommendations

README.dev.rst

``howfairis`` developer documentation
=====================================

If you're looking for user documentation, go `here `_.

|
|

Development install
-------------------

.. code:: shell

    # Create a virtualenv, e.g. with
    python3 -m venv venv3

    # activate virtualenv
    source venv3/bin/activate
    
    # make sure to have a recent version of pip, wheel, setuptools
    python3 -m pip install --upgrade pip wheel setuptools

    # (from the project root directory)
    # install howfairis as an editable package, with development dependencies
    python3 -m pip install --no-cache-dir --editable .[dev]

Afterwards check that the install directory is present on the ``PATH``
environment variable. If so, you should  be able to call the executable,
like so:

.. code:: shell

    howfairis https://github.com//

Running the tests
-----------------

Running the tests requires an activated virtualenv with the development tools installed.

.. code:: shell

    # unit tests with mocked representations of repository behavior
    pytest
    pytest tests/
    
    # live tests with actual repository behavior (slow, prone to HttpError too many requests)
    pytest livetests/
    
    # command line interface tests
    bash clitests/script.sh

Running linters locally
-----------------------

Running the linters requires an activated virtualenv with the development tools installed.

.. code:: shell

    # linter
    prospector

    # recursively check import style for the howfairis module only
    isort --check-only howfairis

    # recursively check import style for the howfairis module only and show
    # any proposed changes as a diff
    isort --check-only --diff howfairis

    # recursively fix  import style for the howfairis module only
    isort howfairis

.. code:: shell

    # requires activated virtualenv with development tools
    prospector && isort --check-only howfairis

You can enable automatic linting with ``prospector`` and ``isort`` on commit like so:

.. code:: shell

    git config --local core.hooksPath .githooks

Versioning
----------

Bumping the version across all files is done with bump2version, e.g.

.. code:: shell

    bump2version minor


Making a release
----------------

Preparation
^^^^^^^^^^^

1. Update the ``CHANGELOG.md``
2. Verify that the information in ``CITATION.cff`` is correct
3. Make sure the version has been updated.
4. Run the unit tests with ``pytest tests/``
5. Run the live tests with ``pytest livetests/``
6. Run the clitests with ``bash clitests/script.sh``

PyPI
^^^^

In a new terminal, without an activated virtual environment or a venv3 directory:

.. code:: shell

    # prepare a new directory
    cd $(mktemp -d --tmpdir howfairis.XXXXXX)
    
    # fresh git clone ensures the release has the state of origin/main branch
    git clone https://github.com/fair-software/howfairis.git .
    
    # prepare a clean virtual environment and activate it
    python3 -m venv venv3
    source venv3/bin/activate
    
    # make sure to have a recent version of pip, wheel, setuptools
    python3 -m pip install --upgrade pip wheel setuptools

    # install runtime dependencies and publishing dependencies
    python3 -m pip install --no-cache-dir .[publishing]
    
    # clean up any previously generated artefacts 
    rm -rf howfairis.egg-info
    rm -rf dist
    
    # create the source distribution and the wheel
    python3 setup.py sdist bdist_wheel

    # upload to test pypi instance (requires credentials)
    twine upload --repository-url https://test.pypi.org/legacy/ dist/*

In a new terminal, without an activated virtual environment or a venv3 directory:

.. code:: shell
    
    cd $(mktemp -d --tmpdir howfairis-test.XXXXXX)

    # check you don't have an existing howfairis
    which howfairis
    python3 -m pip uninstall howfairis

    # install in user space from test pypi instance:
    python3 -m pip -v install --user --no-cache-dir \
    --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple howfairis

Check that the package works as it should when installed from pypitest.

Then upload to pypi.org with:

.. code:: shell

    # Back to the first terminal,
    # FINAL STEP: upload to PyPI (requires credentials)
    twine upload dist/*

GitHub and Zenodo
^^^^^^

1. Make a release on GitHub
2. Verify that making the GitHub release triggered Zenodo into making an archived snapshot of the release.

DockerHub
^^^^^^^^^

To build the image, run:

.. code:: shell

    docker build -t fairsoftware/howfairis:latest .
    
.. code:: shell

    VERSION=$(howfairis --version | sed 's/version: //g')
    docker tag fairsoftware/howfairis:latest fairsoftware/howfairis:${VERSION}

Check that you have the tags you want with:

.. code:: shell

    docker images

Test the docker image with:

.. code:: shell

    docker run -ti --rm fairsoftware/howfairis:latest --help
    docker run -ti --rm fairsoftware/howfairis:latest --version
    docker run -ti --rm fairsoftware/howfairis:latest https://github.com/fair-software/howfairis-livetest
    docker run -ti --rm fairsoftware/howfairis:latest https://gitlab.com/jspaaks/howfairis-livetest
    
    # check what's inside the docker container with
    docker run -ti --rm --entrypoint /bin/sh fairsoftware/howfairis:latest

To push the image to DockerHub, run:

.. code:: shell

    # (requires credentials)  
    docker login
    docker push fairsoftware/howfairis:${VERSION}
    docker push fairsoftware/howfairis:latest    
    
    # log out again to avoid uploading images from other projects
    # later using credentials from this project
    docker logout
    
The new image and its tags should now be listed here https://hub.docker.com/r/fairsoftware/howfairis/tags?page=1&ordering=last_updated.
    

Owner

Citation (CITATION.cff)

# YAML 1.2
---
abstract: "Command line tool to analyze compliance with the five recommendations for FAIR software from https://fair-software.eu."
authors:
  -
    affiliation: "Netherlands eScience Center"
    family-names: Spaaks
    given-names: "Jurriaan H."
    orcid: "https://orcid.org/0000-0002-7064-4069"
  -
    affiliation: "Netherlands eScience Center"
    family-names: Verhoeven
    given-names: Stefan
    orcid: "https://orcid.org/0000-0002-5821-2060"
  -
    affiliation: "Netherlands eScience Center"
    family-names: Tjong Kim Sang
    given-names:  Erik
    orcid: "https://orcid.org/0000-0002-8431-081X"
  -
    affiliation: "Netherlands eScience Center"
    family-names: Diblen
    given-names: Faruk
    orcid: "https://orcid.org/0000-0002-0989-929X"
  -
    affiliation: "Netherlands eScience Center"
    family-names: "Martinez-Ortiz"
    given-names: Carlos
    orcid: "https://orcid.org/0000-0001-5565-7577"
  -
    family-names: Etuk
    given-names: Edidiong
    orcid: "https://orcid.org/0000-0002-1511-0523"
  -
    affiliation: "Netherlands eScience Center"
    family-names: Kuzak
    given-names: Mateusz
    orcid: "https://orcid.org/0000-0003-0087-6021"
  -
    affiliation: "Netherlands eScience Center"
    family-names: Werkhoven
    given-names: Ben
    name-particle: van
    orcid: "https://orcid.org/0000-0002-7508-3272"
  -
    affiliation: "Netherlands eScience Center"
    family-names: Soares Siqueira
    given-names: Abel
    orcid: "https://orcid.org/0000-0003-4451-281X"
  -
    affiliation: "California Institute of Technology"
    family-names: Saladi
    given-names: Shyam
    orcid: "https://orcid.org/0000-0001-9701-3059"
  -
    affiliation: "University of Cambridge"
    family-names: Holding
    given-names: Andrew
    orcid: "https://orcid.org/0000-0002-8459-7048"
  -
    affiliation: "Netherlands eScience Center"
    family-names: Kasalica
    given-names: Vedran
    orcid: "https://orcid.org/0000-0002-0097-1056"
  -
    affiliation: "GSI Helmholtzzentrum für Schwerionenforschung"
    family-names: Kretz
    given-names: Matthias
    orcid: "https://orcid.org/0000-0002-0867-243X"
cff-version: "1.2.0"
date-released: "2022-09-01"
keywords:
  - "FAIR software"
license: "Apache-2.0"
message: "If you use this software, please cite it using these metadata."
repository-code: "https://github.com/fair-software/howfairis"
title: howfairis
version: "0.15.0"
...

GitHub Events

Committers

Last synced: almost 3 years ago

Issues and Pull Requests

Last synced: 6 months ago

Packages