2019-08-09 15:31:56 +02:00
# Contributing to podman-compose
2023-09-21 23:32:21 +02:00
## Who can contribute?
2023-04-08 21:10:23 +02:00
- Users that found a bug
2023-09-21 23:32:21 +02:00
- Users that want to propose new functionalities or enhancements
2023-04-08 21:10:23 +02:00
- 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
2023-09-21 23:32:21 +02:00
Please request your pull request to be merged into the `devel` branch.
2023-04-08 21:10:23 +02:00
Changes to the `stable` branch are managed by the repository maintainers.
## Development environment setup
Note: Some steps are OPTIONAL but all are RECOMMENDED.
2023-09-21 23:32:21 +02:00
1. Fork the project repository and clone it
2023-04-08 21:10:23 +02:00
```shell
$ git clone https://github.com/USERNAME/podman-compose.git
$ cd podman-compose
```
2023-09-21 23:32:21 +02:00
1. (OPTIONAL) Create a Python virtual environment. Example using [virtualenv wrapper ](https://virtualenvwrapper.readthedocs.io/en/latest/ ):
2023-04-08 21:10:23 +02:00
```shell
mkvirtualenv podman-compose
```
2023-09-21 23:32:21 +02:00
2. Install the project runtime and development requirements
2023-04-08 21:10:23 +02:00
```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
2023-09-21 23:32:21 +02:00
5. Run linting and testing before committing code. Ensure all the hooks are passing.
2023-04-08 21:10:23 +02:00
```shell
$ pre-commit run --all-files
```
2023-12-11 00:26:58 +01:00
6. Run code coverage
```shell
2024-03-08 10:00:34 +01:00
coverage run --source podman_compose -m unittest pytests/*.py
python -m unittest tests/*.py
2023-12-11 00:26:58 +01:00
coverage combine
coverage report
coverage html
```
2023-09-21 23:32:21 +02:00
7. Commit your code to your fork's branch.
2023-09-23 12:20:23 +02:00
- 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
2023-09-21 23:32:21 +02:00
- 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`
8. Open a pull request to `containers/podman-compose:devel` and wait for a maintainer to review your work.
2023-04-08 21:10:23 +02:00
2019-08-09 15:31:56 +02:00
## Adding new commands
2023-09-21 23:32:21 +02:00
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:
2019-08-09 15:31:56 +02:00
```
@cmd_run (podman_compose, 'build', 'build images defined in the stack')
2023-12-11 00:26:58 +01:00
async def compose_build(compose, args):
await compose.podman.run(['build', 'something'])
2019-08-09 15:31:56 +02:00
```
## Command arguments parsing
2023-09-21 23:32:21 +02:00
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.
2019-08-09 15:31:56 +02:00
2023-09-21 23:32:21 +02:00
Here is an example:
2019-08-09 15:31:56 +02:00
```
@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`
2023-09-21 23:32:21 +02:00
## Calling a command from another one
2019-08-09 15:31:56 +02:00
2023-09-21 23:32:21 +02:00
If you need to call `podman-compose down` from `podman-compose up`
2019-08-09 15:31:56 +02:00
do something like:
```
@cmd_run (podman_compose, 'up', 'up desc')
2023-12-11 00:26:58 +01:00
async def compose_up(compose, args):
await compose.commands['down'](compose, args)
2019-08-09 15:31:56 +02:00
# or
2023-12-11 00:26:58 +01:00
await compose.commands['down'](argparse.Namespace(foo=123))
2019-08-09 15:31:56 +02:00
```
## Missing Commands (help needed)
2021-09-23 11:42:28 +02:00
```
2019-08-09 15:31:56 +02:00
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
2021-09-23 11:42:28 +02:00
```