CONTRIBUTING.md

Contributing

This documents explains the processes and practices recommended for contributing enhancements to this project.

• Generally, before developing enhancements to this project, you should consider opening an issue explaining your use case.
• If you would like to chat with us about your use-cases or proposed implementation, you can reach us at Canonical Mattermost public channel or Discourse.
• Familiarising yourself with the Charmed Operator Framework library will help you a lot when working on new features or bug fixes.
• All enhancements require review before being merged. Code review typically examines:
  • code quality
  • test coverage
  • user experience
• When evaluating design decisions, we optimize for the following personas, in descending order of priority:
  • charm authors and maintainers
  • the contributors to this codebase
  • juju developers
• Please help us out in ensuring easy to review branches by rebasing your pull request branch onto the main branch. This also avoids merge commits and creates a linear Git commit history.

Notable design decisions

• The State object is immutable from the perspective of the test writer. At the moment there is some hackery here and there (object.__setattr__...) to bypass the read-only dataclass for when the charm code mutates the state; at some point it would be nice to refactor the code to make that unnecessary.

• At the moment the mocking operates at the level of ops.ModelBackend-mediated hook tool calls. ModelBackend would Popen hook tool calls, but Scenario patches the methods that would call Popen, which is therefore never called. Instead, values are returned according to the State. We could consider allowing to operate in increasing levels of stricter confinement:

  • Actually generate hook tool scripts that read/write from/to State, making patching ModelBackend unnecessary.
  • On top of that, run the whole simulation in a container.

Developing

To set up the dependencies you can run: pip install . ; pip uninstall ops-scenario

We recommend using the provided pre-commit config. For how to set up git pre-commit: see here. If you dislike that, you can always manually remember to tox -e lint before you push.

Testing

tox -e fmt           # auto-fix your code as much as possible, including formatting and linting
tox -e lint          # code style
tox -e unit          # unit tests
tox -e lint-tests    # lint testing code
tox                  # runs 'lint', 'lint-tests' and 'unit' environments