Quickstart

In this guide, we will walk through an example flask project and how can you use peltak to manage it. Our app will be a very simple simple TODO app API.

Configure test runner with peltak

In our pelconf.yaml configuration, we will define a test script that will run all of our unit test with some default configuration:

pelconf_version: '1'

scripts:
  test:
    about: Run unit tests
    command: |
      pytest test/unit

This is the simplest version of that command, but it will only tell us whether the tests passed or not. It would be nice if we could also generate coverage report and see the slowest tests (so we can quickly see if some tests take suspiciously large amount of time to execute). Here’s the full setup for tests:

pelconf_version: '1'
build_dir: '.build'

scripts:
  test:
    about: Run unit tests
    command: |
      pytest -c tools/pytest.ini \
          --cov-config=tools/coverage.ini \
          --cov=src/todo_api \
          --cov-report=term \
          --cov-report=html:{{ conf.build_dir }}/coverage \
          .

As you can see, we defined an extra config value build_dir. Right now we use it only in one place so it might not be necessary, but once we start integrating other tools, we can share that value so it’s easier to maintain and change in the future (if needed). This also shows how easy it is to define your own config values and use them in your scripts.

Now you can run tests in your projects with a simple command:

peltak run test

We can actually make it even more simple, by attaching our script to the root peltak command. To do so, we only need to set root_cli to true in our script config:

pelconf_version: '1'
build_dir: '.build'

scripts:
  test:
    about: Run unit tests
    root_cli: true
    command: |
      pytest -c tools/pytest.ini \
          --cov-config=tools/coverage.ini \
          --cov=src/todo_api \
          --cov-report=term \
          --cov-report=html:{{ conf.build_dir }}/coverage \
          .

Now you can run your script with:

peltak test

Configure code check tools (linters) with peltak

Another thing you would probably use on a project are various code checkers. Often times you will have more than one. One of the issues you might run into is how different tools handle filtering files. It might be the case you need to write 2 sets of completely different file filters just to get the same file list as a result. peltak comes with a built in method of filtering files and injecting them into your scripts. This way you can bypass the built-in filters and just pass the pre-filtered list of files to any of the tools you use in your script.

To use it, you have to define a files: section in your script config where you define filtering rules. Then in your script you will have a {{ files }} template variable that you can use. This is a list of strings, so be careful how you pass at to your tools. There is a built-in filter wrap_paths to help you with getting the files ready to pass to a command line. It will wrap all items in the given array with double quotes, making sure you don’t have unexpected errors due to paths having spaces, etc.

Here’s an example of pylint + mypy based lint script:

pelconf_version: '1'
build_dir: '.build'

scripts:
  lint:
    about: Run code checks (pylint + mypy)
    root_cli: true
    files:
      paths:
        - src/todo_api
        - test/unit
      include: "*.py"
      use_gitignore: true
    command: |
      set -e

      mypy --ignore-missing-imports {{ files | wrap_paths }}
      pylint --rcfile tools/pylint.ini {{ files | wrap_paths }}

Using git-flow with peltak

peltak comes bundled with few commands that implement the full git-flow. Those can be a real help if you and your team are using git-flow. The commands themselves have a pretty straightforward implementation as well so if you would like to automate a different kind of work-flow your team is using, looking at the peltak.extra.gitflow commands implementation can be a good start in implementing your own commands.

The git-flow commands are not enabled by default. You need to explicitly enable them using the commands: section in pelconf.yaml:

pelconf_version: '1'

commands:
  - peltak.extra.gitflow

If you have used peltak init to generate the initial configuration than those the gitflow commands will be enabled for you already.

There are 3 main command groups: feature, release and hotfix. Each of them has a set of commands to manage the given branch (be it feature, hotfix or release). The commands are:

start

Will create the branch. The feature/ and release/ branches must always be created from the develop branch and the hotfix/ branches from the master branch. When creating the feature and hotfix branch it will ask you the feature name and create a branch in format feature/<feature_name_in_lowercase_underscore>. The release branch will always be release/<released_ver>.

merged

This command will cleanup after the given branch is merged remotely (eg on github). This will:

1. Checkout the target branch

2. Pull the merged changes,

3. delete the merged branch locally

4. run git fetch --prune to remove the references to the merged remote branch.

finish

This will merge the branch locally and cleanup:

1. Checkout the target branch

2. Merge the branch we want to merge (be it feature, hotfix or release.

3. Delete the merged branch

Feature life-cycle

Let’s see how we would manage a git-flow feature branch with peltak.

Release life-cycle