Contributing to Pungi

Set up development environment

In order to work on Pungi, you should install recent version of Fedora.

Python2

Fedora 29 is recommended because some packages are not available in newer Fedora release, e.g. python2-libcomps.

Install required packages

$ sudo dnf install -y krb5-devel gcc make libcurl-devel python2-devel python2-createrepo_c kobo-rpmlib yum python2-libcomps python2-libselinx

Python3

Install required packages

$ sudo dnf install -y krb5-devel gcc make libcurl-devel python3-devel python3-createrepo_c python3-libcomps

Developing

Currently the development workflow for Pungi is on master branch:

• Make your own fork at https://pagure.io/pungi

• Clone your fork locally (replacing $USERNAME with your own):

  git clone git@pagure.io:forks/$USERNAME/pungi.git
  

• cd into your local clone and add the remote upstream for rebasing:

  cd pungi
  git remote add upstream git@pagure.io:pungi.git
  

  Note

  This workflow assumes that you never git commit directly to the master branch of your fork. This will make more sense when we cover rebasing below.

• create a topic branch based on master:

  git branch my_topic_branch master
  git checkout my_topic_branch
  

• Make edits, changes, add new features, etc. and then make sure to pull from upstream master and rebase before submitting a pull request:

  # lets just say you edited setup.py for sake of argument
  git checkout my_topic_branch
  
  # make changes to setup.py
  black setup.py
  tox
  git add setup.py
  git commit -s -m "added awesome feature to setup.py"
  
  # now we rebase
  git checkout master
  git pull --rebase upstream master
  git push origin master
  git push origin --tags
  git checkout my_topic_branch
  git rebase master
  
  # resolve merge conflicts if any as a result of your development in
  # your topic branch
  git push origin my_topic_branch
  

  Note

  In order to for your commit to be merged:

  • you must sign-off on it. Use -s option when running git commit.

  • The code must be well formatted via black and pass flake8 checking. Run tox -e black,flake8 to do the check.

• Create pull request in the pagure.io web UI

• For convenience, here is a bash shell function that can be placed in your ~/.bashrc and called such as pullupstream pungi-4-devel that will automate a large portion of the rebase steps from above:

  pullupstream () {
    if [[ -z "$1" ]]; then
      printf "Error: must specify a branch name (e.g. - master, devel)\n"
    else
      pullup_startbranch=$(git describe --contains --all HEAD)
      git checkout $1
      git pull --rebase upstream master
      git push origin $1
      git push origin --tags
      git checkout ${pullup_startbranch}
    fi
  }
  

Testing

You must write unit tests for any new code (except for trivial changes). Any code without sufficient test coverage may not be merged.

To run all existing tests, suggested method is to use tox.

$ sudo dnf install python3-tox -y

$ tox -e py3
$ tox -e py27

Alternatively you could create a vitualenv, install deps and run tests manually if you don’t want to use tox.

$ sudo dnf install python3-virtualenvwrapper -y
$ mkvirtualenv --system-site-packages py3
$ workon py3
$ pip install -r requirements.txt -r test-requirements.txt
$ make test

# or with coverage
$ make test-coverage

If you need to run specified tests, pytest is recommended.

# Activate virtualenv first

# Run tests
$ pytest tests/test_config.py
$ pytest tests/test_config.py -k test_pkgset_mismatch_repos

In the tests/ directory there is a shell script test_compose.sh that you can use to try and create a miniature compose on dummy data. The actual data will be created by running make test-data in project root.

$ sudo dnf -y install rpm-build createrepo_c isomd5sum genisoimage syslinux

# Activate virtualenv (the one created by tox could be used)
$ source .tox/py3/bin/activate

$ python setup.py develop
$ make test-data
$ make test-compose

This testing compose does not actually use all phases that are available, and there is no checking that the result is correct. It only tells you whether it crashed or not.

Note

Even when it finishes successfully, it may print errors about repoclosure on Server-Gluster.x86_64 in test phase. This is not a bug.

Documenting

You must write documentation for any new features and functional changes. Any code without sufficient documentation may not be merged.

To generate the documentation, run make doc in project root.