diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 97dbb61..b8481dc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,15 +1,48 @@ -# Contributing +# How to contribute -To make contributions to this charm, you'll need a working [development setup](https://juju.is/docs/sdk/dev-setup). +## Overview -You can create an environment for development with `tox`: +This document explains the processes and practices recommended for contributing enhancements to the SMTP Relay operator. + +- Generally, before developing enhancements to this charm, you should consider [opening an issue + ](https://github.com/canonical/smtp-relay-operator/issues) 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 Matrix public channel](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) + or [Discourse](https://discourse.charmhub.io/). +- Familiarizing yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) 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 for Juju operators of this charm. +- 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. +- Please generate src documentation for every commit. See the section below for more details. + +## Developing + +The code for this charm can be downloaded as follows: + +``` +git clone https://github.com/canonical/smtp-relay-operator +``` + +You can use the environments created by `tox` for development: ```shell -tox devenv -e integration -source venv/bin/activate +tox --notest -e unit +source .tox/unit/bin/activate ``` -## Generating src docs for every commit +### Testing + +* `tox`: Runs all of the basic checks (`lint`, `unit`, `static`, and `coverage-report`). +* `tox -e fmt`: Runs formatting using `black` and `isort`. +* `tox -e lint`: Runs a range of static code analysis to check the code. +* `tox -e static`: Runs other checks such as `bandit` for security issues. +* `tox -e unit`: Runs the unit tests. +* `tox -e integration`: Runs the integration tests. + +### Generating src docs for every commit Run the following command: @@ -18,25 +51,25 @@ echo -e "tox -e src-docs\ngit add src-docs\n" >> .git/hooks/pre-commit chmod +x .git/hooks/pre-commit ``` -## Testing +## Build charm -This project uses `tox` for managing test environments. There are some pre-configured environments -that can be used for linting and formatting code when you're preparing contributions to the charm: +Build the charm in this git repository using: ```shell -tox run -e format # update your code according to linting rules -tox run -e lint # code style -tox run -e unit # unit tests -tox run -e integration # integration tests -tox # runs 'format', 'lint', and 'unit' environments +charmcraft pack ``` -## Build the charm - -Build the charm in this git repository using: +### Deploy -```shell -charmcraft pack +```bash +# Create a model +juju add-model smtp-relay-dev +# Enable DEBUG logging +juju model-config logging-config="=INFO;unit=DEBUG" +# Deploy the charm (assuming you're on amd64) +juju deploy ./smtp_relay_ubuntu-24.04-amd64.charm ``` - +* [Developer documentation](https://www.postfix.org/documentation.html) +* [Official webpage](https://www.postfix.org/) +* [Troubleshooting](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) +## Project and community +* [Issues](https://github.com/canonical/smtp-relay-operator/issues) +* [Contributing](https://charmhub.io/smtp-relay/docs/how-to-contribute) +* [Matrix](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) -For more details, [see here](https://charmhub.io/smtp-relay/configure). diff --git a/docs/how-to/contribute.md b/docs/how-to/contribute.md new file mode 100644 index 0000000..1abf4bc --- /dev/null +++ b/docs/how-to/contribute.md @@ -0,0 +1,3 @@ +# How to contribute + +See [the contributing guide](https://github.com/canonical/smtp-relay-operator/blob/main/CONTRIBUTING.md). diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..965d8db --- /dev/null +++ b/docs/index.md @@ -0,0 +1,50 @@ +# SMTP Relay Operator + +A [Juju](https://juju.is/) [charm](https://juju.is/docs/olm/charmed-operators) +deploying and managing a postfix SMTP relay server on bare metal. SMTP +is an Internet standard communication protocol for email transmission. + +Features include (not limited to): +- set up base Postfix system +- relay through another MTA +- set up virtual aliases and transport maps +- restrict relaying per domain, sender, recipient, headers checks +- enable SPF subsystem +- set up authenticated submission service +- restrict sender address per user +- fine-tune TLS settings +- set up limits (rate, size, connections, ...) +- set up Nagios monitoring + +For information about how to deploy, integrate, and manage this charm, see the Official [smtp-relay Operator Documentation](https://charmhub.io/smtp-relay/docs). + +## In this documentation + +| | | +|--|--| +| [How-to guides](https://charmhub.io/smtp-relay/docs/how-to-contribute)
Step-by-step guides covering key operations and common tasks | +| [Reference](https://charmhub.io/smtp-relay/docs/reference-actions)
Technical information - specifications, APIs, architecture | + +## Contributing to this documentation + +Documentation is an important part of this project, and we take the same open-source approach to the documentation as the code. As such, we welcome community contributions, suggestions and constructive feedback on our documentation. Our documentation is hosted on the [Charmhub forum](https://discourse.charmhub.io/t/smtp-relay-documentation-overview/16137) to enable easy collaboration. Please use the "Help us improve this documentation" links on each documentation page to either directly change something you see that's wrong, ask a question, or make a suggestion about a potential change via the comments section. + +If there's a particular area of documentation that you'd like to see that's missing, please [file a bug](https://github.com/canonical/smtp-relay-operator/issues). + +## Project and community + +The SMTP Relay Operator is a member of the Ubuntu family. It's an open-source project that warmly welcomes community projects, contributions, suggestions, fixes, and constructive feedback. + +- [Code of conduct](https://ubuntu.com/community/code-of-conduct) +- [Get support](https://discourse.charmhub.io/) +- [Join our online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) +- [Contribute](https://github.com/canonical/smtp-relay-operator/blob/main/CONTRIBUTING.md) + +Thinking about using the SMTP Relay Operator for your next project? [Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)! + +# Navigation + +| Level | Path | Navlink | +| --- | --- | --- | +| 1 | how-to | [How to]() | +| 1 | reference | [Reference]() | diff --git a/docs/reference/actions.md b/docs/reference/actions.md new file mode 100644 index 0000000..4e942f2 --- /dev/null +++ b/docs/reference/actions.md @@ -0,0 +1,5 @@ +# Actions + +See [Actions](https://charmhub.io/smtp-relay/actions). + +> Read more about actions in the Juju docs: [Action](https://juju.is/docs/juju/action) diff --git a/docs/reference/external_access.md b/docs/reference/external_access.md new file mode 100644 index 0000000..f729701 --- /dev/null +++ b/docs/reference/external_access.md @@ -0,0 +1,3 @@ +# External access + +This charm does not require any external access.