Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add DESIGN_PRINCIPLES #420

Merged
merged 3 commits into from
Feb 10, 2023
Merged

Add DESIGN_PRINCIPLES #420

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e700d7a
Add DESIGN_PRINCIPLES.md draft
thomaseizinger Oct 28, 2022
ae60839
Add "ease of use" paragraph
thomaseizinger Oct 28, 2022
c3bebaa
Apply suggestions from code review
thomaseizinger Oct 31, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions DESIGN_PRINCIPLES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Design principles

This document aims to capture the design principles that went into this library.
It should serve as a reference point when making decisions on what features to include or exclude.

## Simple
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Loved this section, thanks for adding it!


One of the most important goals that we want to adhere to is creating a _simple_ API.
Overall, this means keeping the API as small as possible to get the task done.
When in doubt, we'd rather not add flags or configuration options for certain use cases.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a pretty big point, we like to emphasize for the Testcontainers project as a whole. Testcontainers does not intend to be a generic Docker client or a replacement for the Docker CLI. Instead, we follow an opinionated approach of providing APIs that make using best practices for integration testing easier.

While it is technically possible to map to fixed ports, or specify fixed container names, we believe that this feature is actually not necessary for the intended use cases of Testcontainers, hence we would hesitate to just add all Docker capabilities to the Testcontainers API, without a good reason for the integration testing context.


Tests should be easier to write, easy to understand and easy to maintain.
`testcontainers` aims to support this as much as possible.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The umbrella project is called Testcontainers. The implementation for the individual languages is called Testcontainers for {$lang} and the repository is called testcontainers-${rust}.

In think in this instance, it is indeed referring to Testcontainers in general and to Testcontainers for Rust in particular 🙂

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I intended to refer to the crate name here :D

Would you like it to be rewritten?

Having too many configuration options makes it harder for users to achieve this goal.

Another advantage of a small, public API is that we have to make fewer breaking changes.
This makes upgrades easier for our users.

## Reliable

Tests need to be reliable to provide value.
We strive to make `testcontainers` as reliable as possible and try to control as many aspects of the container to make sure they work consistently.

One consequence of this decision is that the container _tag_ is typically not configurable for images that ship with `testcontainers`.
Whilst an image behind a tag can also change, image authors tend to preserve compatibility there.
If we were to allow users to change the `tag` of an image, we wouldn't be able to guarantee that it works because we cannot test all combinations.
Comment on lines +24 to +26
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For this, we added the compatible substitute mechanism to Testcontainers for Java: https://www.testcontainers.org/features/image_name_substitution/#manual-substitution

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure if it is entirely the same. From these docs, I'd say the difference is that testcontainers for Rust doesn't even allow the following line:

DockerImageName.parse("mysql:8.0.24")


## Ease of use

The library should be easy to use.
For example, users should be able to make their own implementation of `Image` without much boilerplate.
In fact, the path forward may very well be that we stop shipping a lot of images in the crate and instead require users to create their own images.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I highly support this path forward. While yes, there's a lot of often-used containers, the fact anyone can use any container is really the key for me. I use oddball containers and would not expect to upstream them into this crate.