extern/podman-compose
1
0
Fork 1
mirror of https://github.com/containers/podman-compose.git synced 2025-06-20 11:47:50 +02:00
Code Issues Packages Projects Releases Wiki Activity

Formats CONTRIBUTING.md

Browse Source 
Signed-off-by: Jean-Baptiste Perez <jbaptperez@gmail.com>
This commit is contained in:
Jean-Baptiste Perez 2023-09-21 23:34:22 +02:00
parent b263dc1a7d
commit 81d81fb303
1 changed files with 74 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

93
CONTRIBUTING.md
View File

@ -2,11 +2,11 @@
## Who can contribute? ## Who can contribute?
- Users that found a bug - Users that found a bug,
- Users that want to propose new functionalities or enhancements - Users that want to propose new functionalities or enhancements,
- Users that want to help other users to troubleshoot their environments - Users that want to help other users to troubleshoot their environments,
- Developers that want to fix bugs - Developers that want to fix bugs,
- Developers that want to implement new functionalities or enhancements - Developers that want to implement new functionalities or enhancements.
## Branches ## Branches
@ -17,54 +17,73 @@ Changes to the `stable` branch are managed by the repository maintainers.
Note: Some steps are OPTIONAL but all are RECOMMENDED. Note: Some steps are OPTIONAL but all are RECOMMENDED.
1. Fork the project repository and clone it 1. Fork the project repository and clone it:
```shell ```shell
$ git clone https://github.com/USERNAME/podman-compose.git $ git clone https://github.com/USERNAME/podman-compose.git
$ cd podman-compose $ cd podman-compose
``` ```
1. (OPTIONAL) Create a Python virtual environment. Example using [virtualenv wrapper](https://virtualenvwrapper.readthedocs.io/en/latest/):
2. (OPTIONAL) Create a Python virtual environment. Example using
[virtualenv wrapper](https://virtualenvwrapper.readthedocs.io/en/latest/):
```shell ```shell
mkvirtualenv podman-compose $ mkvirtualenv podman-compose
``` ```
2. Install the project runtime and development requirements
3. Install the project runtime and development requirements:
```shell ```shell
$ pip install '.[devel]' $ pip install '.[devel]'
``` ```
3. (OPTIONAL) Install `pre-commit` git hook scripts (https://pre-commit.com/#3-install-the-git-hook-scripts)
4. (OPTIONAL) Install `pre-commit` git hook scripts
(https://pre-commit.com/#3-install-the-git-hook-scripts):
```shell ```shell
$ pre-commit install $ pre-commit install
``` ```
4. Create a new branch, develop and add tests when possible
5. Run linting and testing before committing code. Ensure all the hooks are passing. 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 ```shell
$ pre-commit run --all-files $ pre-commit run --all-files
``` ```
6. Run code coverage
7. Run code coverage:
```shell ```shell
coverage run --source podman_compose -m unittest pytests/*.py $ coverage run --source podman_compose -m unittest pytests/*.py
python -m unittest tests/*.py $ python -m unittest tests/*.py
coverage combine $ coverage combine
coverage report $ coverage report
coverage html $ 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://github.com/containers/common/blob/main/CONTRIBUTING.md#sign-your-prs) to learn how to sign your commits 8. Commit your code to your fork's branch.
- 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` - Make sure you include a `Signed-off-by` message in your commits.
8. Open a pull request to `containers/podman-compose:devel` and wait for a maintainer to review your work. 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 ## Adding new commands
To add a command, you need to add a function that is decorated with `@cmd_run`. 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 The decorated function must be declared `async` and should accept two arguments: The compose
command-specific arguments (resulted from the Python's `argparse` package). 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`, In this function, you can run Podman (e.g. `await compose.podman.run(['inspect', 'something'])`),
`compose.containers` etc. access `compose.pods`, `compose.containers` etc.
Here is an example: Here is an example:
``` ```python
@cmd_run(podman_compose, 'build', 'build images defined in the stack') @cmd_run(podman_compose, 'build', 'build images defined in the stack')
async def compose_build(compose, args): async def compose_build(compose, args):
await compose.podman.run(['build', 'something']) await compose.podman.run(['build', 'something'])
@ -72,8 +91,9 @@ async def compose_build(compose, args):
## Command arguments parsing ## 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 To add arguments to be parsed by a command, you need to add a function that is decorated with
the compose instance and the command's name (as a string list or as a single string). `@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`. The decorated function should accept a single argument: An instance of `argparse`.
@ -83,23 +103,24 @@ Note you can add such a function multiple times.
Here is an example: Here is an example:
``` ```python
@cmd_parse(podman_compose, 'build') @cmd_parse(podman_compose, 'build')
def compose_build_parse(parser): def compose_build_parse(parser):
parser.add_argument("--pull", parser.add_argument("--pull",
help="attempt to pull a newer version of the image", action='store_true') help="attempt to pull a newer version of the image", action='store_true')
parser.add_argument("--pull-always", 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 another one ## Calling a command from another one
If you need to call `podman-compose down` from `podman-compose up` If you need to call `podman-compose down` from `podman-compose up`, do something like:
do something like:
``` ```python
@cmd_run(podman_compose, 'up', 'up desc') @cmd_run(podman_compose, 'up', 'up desc')
async def compose_up(compose, args): async def compose_up(compose, args):
await compose.commands['down'](compose, args) await compose.commands['down'](compose, args)
@ -107,8 +128,8 @@ async def compose_up(compose, args):
await compose.commands['down'](argparse.Namespace(foo=123)) await compose.commands['down'](argparse.Namespace(foo=123))
``` ```
## Missing Commands (help needed) ## Missing Commands (help needed)
``` ```
bundle Generate a Docker bundle from the Compose file bundle Generate a Docker bundle from the Compose file
create Create services create Create services