hsoj/dubilier

dubilier

A Discord bot providing a modular command structure with the primary focus of managing users within a ham radio club's server.

Contributing

The development workflow is very close to a trunk based development flow, with a minor addition that the primary development branch is develop with any and all code that is merged into the main branch considered as "production ready".

Preparing Development Environment

Currently the suggested development environment is focused on Linux using the Ubuntu distribution, however, the following steps could be applied to your distro of choice.

Install system level packages

sudo apt-get update
sudo apt-get install -y python3.9 python3-pip python3-venv

Create Python environment

NOTE: This should be done at the root level of the repository in order to avoid any potential conflicts.

python3 -m venv .venv
source .venv/bin/activate

Install development dependencies

NOTE: This assumes that the venv for the project has been activated.

python3 -m pip install -Ue .[dev]

Test development environment

NOTE: This should be ran prior to making any changes to ensure that a passing result is experienced.

NOTE: This should be ran at the root level of the repository and assumes that the venv for the project has been activated.

tox

In the event that tox exits successfully, the development environment setup is complete.

dubilier's Issues

Refactor Discord Daemon object to inherit directly from Bot object

Context

Due to the way that the Discord Bot object loads Cog objects, until there is an ability to lessen the code smell presented, for now the Daemon object should just inherit directly from the Bot object and just use the pattern that is expected from upstream.

Out of scope

• Figuring out how to remove the code smell
• Overriding the setup_hook or load_extension methods to not rely on "magic"

Acceptance criteria

• Daemon object inherits directly from the discord.ext.commands.Bot object
• Process successfully connects to Discord
• An example command can be executed

Technical notes

No response

Discovery for documentation

Context

Need space to put documentation that is manually created as well as introduce tooling that will automatically generate documentation based on Python docstrings.

Out of scope

• Pipeline runs auto-generation
• Deployment of generated docs

Acceptance criteria

• Tooling for auto-generating documentation is decided
• Location for generated documentation is decided

Technical notes

No response

Add security check workflow

Context

Since there are third-party dependencies, there should be a workflow that is ran when changes are made to the develop branch to ensure that the versions pinned within the setuptools configuration do not contain known vulnerabilities. Additionally, any other provided action which is relevant is included within the workflow.

Out of context

• Workflow execution order

Acceptance criteria

• Workflow executes when changes are made to the develop branch
• Runs at least a dependency check for third-party modules
• Any additional security check that is relevant is added

Provide a cleaner mechanism for loading cogs

Context

The latest version of the discord Python module, has taken the approach of having "extensions" loaded using a module spec; which expects a module level method setup to exist in order to add a cog into the overall bot. This creates code smell when a lot of cogs exist within the bot's capabilities, and it is preferred to eliminate this smell so creating a more modular system is a bit more straight forward for the implementation layer.

Out of scope

• Auto-discovery of extensions

Acceptance criteria

• Adding an extension no longer requires the global setup module method
• Able to call commands defined within the extension

Technical notes

https://docs.python.org/3/library/importlib.html
importlib.machinery.ModuleSpec is used to load the Python module for the extension.

Add a README

Context

A README.md file should be provided that initially provides the steps required to get the development environment set up. It should call out any system level packages, install development dependencies as well as how to run the testing tooling.

Acceptance Criteria

• README.md file exists
• Steps to get a development environment are properly documented

Determine a good method of auto versioning

Context

Currently, the version of the project has to be supplied as a hardcoded value within the setuptools configuration. In order to have the version automatically bumped from a successful workflow, there needs to be a mechanism which will increment the version.

Out of scope

• Incrementing the minor version based on milestone completion
• Incrementing the major version from PR / merge into the main branch

Tech notes

Should probably be functionality that exists within a script that can be executed at the end of the test workflow within the develop branch.

Acceptance criteria

• Minor version is incremented after a successful test workflow

Create object to communicate with sqlite

Context

In order to have persistent data, database interactions will be required. For the first pass, leveraging a simple SQlite database will suffice. There needs to be an object that opens and prepares the database for queries and manipulation. Tables and their columns should be definable through code and not expect for a developer to write raw SQL.

Out of scope

• Defining an object which creates the SQL model

Acceptance criteria

• A database can be opened using a memory store
• A database can be opened using a filesystem path

Technical notes

• To simplify things, should just leverage the sqlalchemy package

Create container file

Context

The bot component needs to be able to run within a container using an OCI image. When the container is ran, it should automatically run the daemon for the bot.

Out of scope

• Accessing the auth token securely
• Publishing the container image

Acceptance criteria

• Container image can be built
• The bot daemon runs without having to call the CLI
• There is a workflow in GitHub Actions which builds the container image

Add CI pipelines with GitHub Actions

Context

To start the process of ensuring the code quality adheres to the standards of the project, an initial inclusion of running the testing tooling in the CI pipeline should be performed.

Out Of Scope

• Building any artifacts
• Delivering any artifacts
• Running on any branch other than develop

Acceptance Criteria

• GitHub Actions workflows are ran when ever there is a push to the develop branch.
• Workflow is successful.

Make the click commands add automatically

Context
The click module does not respect decorators leveraged in modules other than where their "parent" is defined. For example, the dubilier.cli.main group does not execute the decorator which is used within dubilier.bot.cli. In order to quickly workaround this, a poor pattern is utilized just so sub-commands are registered within the CLI.

We want to avoid following this pattern, and introduce functionality that will automatically load any sub-command regardless of which package/sub-module the interface exists within.

Acceptance Criteria

• Commands within packages/sub-modules are automatically discovered and added to the root chain.
• The add_command pattern is removed

Tech Notes
Potential path https://stackoverflow.com/questions/50751040/include-submodules-on-click

Create an issue template for bugs

Context

In order to capture needed information for a bug report, a template should be created providing the appropriate fields. This should be done using the same pattern as the feature issue template.

Out of scope

• Determining the exact fields that will be required

Acceptance criteria

• When Create issue is clicked, the "bug" issue type is provided.

Technical notes

• It is understood that this is an initial pass and is expected for the template to change over time.

Create GitHub issue template for feature addition

Context

To simplify adding issues for features that can be refined and moved into "Ready for dev", a GitHub issue template should be created to ensure that at least the required sections are provided.

Out of scope

• Template for bug reports

Acceptance criteria

• A feature issue is created with all of the expected fields completed (or uncompleted if applicable)

Actually load extensions that are found

Context

After #18 we want to actually attempt to load the extension modules found into the bot. Update the dubilier.bot.discord.Daemon.setup_hook method to iterate over extension packages that are provided for the Daemon object.

Out of scope

No response

Acceptance criteria

• All extensions that adhere to the hook pattern are loaded and any command they declare is available.

Technical notes

No response

Pin Python dependency versions

Context

In order to ensure that the Python dependencies are well tested with expected versions, they need to be pinned in the setup.py.

Acceptance Criteria

• All dependencies are pinned to their current versions
• Tests pass after versions are pinned

Refactor code for domain driven design

The code is currently laid out with all of the modules contained within the primary package and should be available from the correct domain instead. Additionally, the pattern used for the entry point is an older style, which should be updated to comply with modern Python application patterns.

Add base bot command object

Context

In order to provide an interface that can easily be discovered, as well as implemented, a base object that provides the required functionality for a bot command to be created is needed. The dubilier.bot.discord.Daemon object should provide a method to include a command into the bot's awareness.

Out of scope

• Not expected to actually be callable, nor visible on the list of available commands the user can execute.

Acceptance criteria

• Base object can be initialized
• Daemon object provides a method to add the command

Technical notes

Previously the Cog object was inherited for this purpose. Should determine if this is still the best approach, and if not, inherit from a more reasonable object if it makes sense to follow this pattern.

Implement SQLAlchemy for DB interactions

In order to simplify creation of the DB models, start to implement SQLAlchemy and model objects instead of relying on handling the connection/communication/creation/etc. to the database.

Remove pre-commit from tox

Context

It's redundant to go through the pre-commit configs within tox.

TBA

Out of scope

No response

Acceptance criteria

TBA

Technical notes

No response

Create functionality to automatically discover extensions

Context

Even with the current path leaning into the code smell required by upstream, there still needs to be functionality which will allow the setup_hook method in the Daemon to actually call the load_extension method based on the packages that exist. This method should discover the available extensions, and return the proper import path for each.

Out of scope

• Removing the code smell of the setup global method expected in each package
• Implementing the call to load_extension

Acceptance criteria

• Method returns a sequence of discovered packages
• A clear definition of what makes an extension discoverable

Technical notes

No response