Skip to content

Latest commit

 

History

History
135 lines (99 loc) · 4.22 KB

CONTRIBUTING.md

File metadata and controls

135 lines (99 loc) · 4.22 KB
Raw

Contributing to podman-compose

Who can contribute?

  • Users that found a bug,
  • Users that want to propose new functionalities or enhancements,
  • Users that want to help other users to troubleshoot their environments,
  • Developers that want to fix bugs,
  • Developers that want to implement new functionalities or enhancements.

Development environment setup

Note: Some steps are OPTIONAL but all are RECOMMENDED.

  1. Fork the project repository and clone it:

    $ git clone https://github.com/USERNAME/podman-compose.git
$ cd podman-compose

  2. (OPTIONAL) Create a Python virtual environment. Example using virtualenv wrapper:

    $ mkvirtualenv podman-compose

  3. Install the project runtime and development requirements:

    $ pip install '.[devel]'

  4. (OPTIONAL) Install pre-commit git hook scripts (https://pre-commit.com/#3-install-the-git-hook-scripts):

    $ pre-commit install

  5. Create a new branch, develop and add tests when possible.

  6. Run linting and testing before committing code. Ensure all the hooks are passing.

    $ pre-commit run --all-files

  7. Run code coverage:

    $ coverage run --source podman_compose -m unittest discover tests/unit
$ python3 -m unittest discover tests/integration
$ coverage combine
$ coverage report
$ coverage html

  8. Commit your code to your fork's branch.

    • Make sure you include a Signed-off-by message in your commits. Read this guide to learn how to sign your commits.
    • In the commit message, reference the Issue ID that your code fixes and a brief description of the changes. Example: Fixes #516: Allow empty network

  9. Open a pull request to containers/podman-compose and wait for a maintainer to review your work.

Adding new commands

To add a command, you need to add a function that is decorated with @cmd_run.

The decorated function must be declared async and should accept two arguments: The compose instance and the command-specific arguments (resulted from the Python's argparse package).

In this function, you can run Podman (e.g. await compose.podman.run(['inspect', 'something'])), access compose.pods, compose.containers etc.

Here is an example:

@cmd_run(podman_compose, 'build', 'build images defined in the stack')
async def compose_build(compose, args):
    await compose.podman.run(['build', 'something'])

Command arguments parsing

To add arguments to be parsed by a command, you need to add a function that is decorated with @cmd_parse which accepts the compose instance and the command's name (as a string list or as a single string).

The decorated function should accept a single argument: An instance of argparse.

In this function, you can call parser.add_argument() to add a new argument to the command.

Note you can add such a function multiple times.

Here is an example:

@cmd_parse(podman_compose, 'build')
def compose_build_parse(parser):
    parser.add_argument("--pull",
        help="attempt to pull a newer version of the image", action='store_true')
    parser.add_argument("--pull-always",
        help="Attempt to pull a newer version of the image, "
             "raise an error even if the image is present locally.",
        action='store_true')

NOTE: @cmd_parse should be after @cmd_run.

Calling a command from another one

If you need to call podman-compose down from podman-compose up, do something like:

@cmd_run(podman_compose, 'up', 'up desc')
async def compose_up(compose, args):
    await compose.commands['down'](compose, args)
    # or
    await compose.commands['down'](argparse.Namespace(foo=123))

Missing Commands (help needed)

  bundle             Generate a Docker bundle from the Compose file
  create             Create services
  events             Receive real time events from containers
  images             List images
  rm                 Remove stopped containers
  scale              Set number of containers for a service
  top                Display the running processes