diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6c0a667..6f98e29 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,70 +1,89 @@ # Contributing to podman-compose -## Who can contribute? +## Who can contribute? -- Users that found a bug -- Users that wants 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 +- 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. ## Branches -Please request your PR to be merged into the `devel` branch. +Please request your pull request to be merged into the `devel` branch. Changes to the `stable` branch are managed by the repository maintainers. ## Development environment setup Note: Some steps are OPTIONAL but all are RECOMMENDED. -1. Fork the project repo and clone it -```shell -$ git clone https://github.com/USERNAME/podman-compose.git -$ cd podman-compose -``` -1. (OPTIONAL) Create a python virtual environment. Example using [virtualenv wrapper](https://virtualenvwrapper.readthedocs.io/en/latest/): -```shell -mkvirtualenv podman-compose -``` -2. Install the project runtime and development requirements -```shell -$ pip install '.[devel]' -``` -3. (OPTIONAL) Install `pre-commit` git hook scripts (https://pre-commit.com/#3-install-the-git-hook-scripts) -```shell -$ pre-commit install -``` -4. Create a new branch, develop and add tests when possible -5. Run linting & testing before committing code. Ensure all the hooks are passing. -```shell -$ pre-commit run --all-files -``` -6. Run code coverage -```shell -coverage run --source podman_compose -m unittest pytests/*.py -python -m unittest tests/*.py -coverage combine -coverage report -coverage html -``` -7. Commit your code to your fork's branch. - - Make sure you include a `Signed-off-by` message in your commits. Read [this guide](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) 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` -7. Open a PR to `containers/podman-compose:devel` and wait for a maintainer to review your work. +1. Fork the project repository and clone it: + + ```shell + $ git clone https://github.com/USERNAME/podman-compose.git + $ cd podman-compose + ``` + +2. (OPTIONAL) Create a Python virtual environment. Example using + [virtualenv wrapper](https://virtualenvwrapper.readthedocs.io/en/latest/): + + ```shell + $ mkvirtualenv podman-compose + ``` + +3. Install the project runtime and development requirements: + + ```shell + $ pip install '.[devel]' + ``` + +4. (OPTIONAL) Install `pre-commit` git hook scripts + (https://pre-commit.com/#3-install-the-git-hook-scripts): + + ```shell + $ 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. + + ```shell + $ pre-commit run --all-files + ``` + +7. Run code coverage: + + ```shell + $ coverage run --source podman_compose -m unittest pytests/*.py + $ python -m unittest tests/*.py + $ 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](https://github.com/containers/common/blob/main/CONTRIBUTING.md#sign-your-prs) + 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:devel` 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` passing the compose instance, command name and -description. This function must be declared `async` the wrapped -function should accept two arguments the compose instance and -the command-specific arguments (resulted from python's `argparse` -package) inside that command you can run PodMan like this -`await compose.podman.run(['inspect', 'something'])`and inside -that function you can access `compose.pods` and `compose.containers` -...etc. Here is an example +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: + +```python @cmd_run(podman_compose, 'build', 'build images defined in the stack') async def compose_build(compose, args): await compose.podman.run(['build', 'something']) @@ -72,31 +91,36 @@ async def compose_build(compose, args): ## Command arguments parsing -Add a function that accept `parser` which is an instance from `argparse`. -In side that function you can call `parser.add_argument()`. -The function decorated with `@cmd_parse` accepting the compose instance, -and command names (as a list or as a string). -You can do this multiple times. +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). -Here is an example +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: + +```python @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') + 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` +NOTE: `@cmd_parse` should be after `@cmd_run`. -## Calling a command from inside another +## Calling a command from another one -If you need to call `podman-compose down` from inside `podman-compose up` -do something like: +If you need to call `podman-compose down` from `podman-compose up`, do something like: -``` +```python @cmd_run(podman_compose, 'up', 'up desc') async def compose_up(compose, args): await compose.commands['down'](compose, args) @@ -104,8 +128,8 @@ async def compose_up(compose, args): await compose.commands['down'](argparse.Namespace(foo=123)) ``` - ## Missing Commands (help needed) + ``` bundle Generate a Docker bundle from the Compose file create Create services diff --git a/setup.py b/setup.py index 8f7a4e9..1417b52 100644 --- a/setup.py +++ b/setup.py @@ -40,7 +40,7 @@ setup( "pyyaml", "python-dotenv", ], - extras_require={"devel": ["ruff", "pre-commit", "coverage", "parameterize"]}, + extras_require={"devel": ["ruff", "pre-commit", "coverage", "parameterized"]}, # test_suite='tests', # tests_require=[ # 'coverage',