fix(core): bad rebase from #579 (#635)

fixes some incorrectly resolved conflicts during the rebase in #579 fixes #632 - **fix #607 - no longer need to manually include for toctree** - **semver note** - **fix rest of incorrectly resolved conflicts in index.rst**
testcontainers · Jul 2, 2024 · 4766e48 · 4766e48
1 parent e93bc29
commit 4766e48
Show file tree

Hide file tree

Showing 2 changed files with 70 additions and 24 deletions.
diff --git a/.github/PULL_REQUEST_TEMPLATE/new_container.md b/.github/PULL_REQUEST_TEMPLATE/new_container.md
@@ -14,22 +14,26 @@ It helps reduce unnecessary work for you and the maintainers!
 
 - [ ] Your PR title follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) syntax
   as we make use of this for detecting Semantic Versioning changes.
+  - Additions to the community modules do not contribute to SemVer scheme:
+    all community features will be tagged [community-feat](https://github.com/testcontainers/testcontainers-python/issues?q=label%3Acommunity-feat+),
+    but we do not want to release minor or major versions due to features or breaking changes outside of core.
+    So please use `fix(postgres):` or `fix(my_new_vector_db):` if you want to add or modify community modules.
+    This may change in the future if we have a separate package released with community modules.
 - [ ] Your PR allows maintainers to edit your branch, this will speed up resolving minor issues!
 - [ ] The new container is implemented under `modules/*`
   - Your module follows [PEP 420](https://peps.python.org/pep-0420/) with implicit namespace packages
     (if unsure, look at other existing community modules)
   - Your package namespacing follows `testcontainers.<modulename>.*`
     and you DO NOT have an `__init__.py` above your module's level.
-  - Your module has it's own tests under `modules/*/tests`
+  - Your module has its own tests under `modules/*/tests`
   - Your module has a `README.rst` and hooks in the `.. auto-class` and `.. title` of your container
   - Implement the new feature (typically in `__init__.py`) and corresponding tests.
 - [ ] Your module is added in `pyproject.toml`
   - it is declared under `tool.poetry.packages` - see other community modules
   - it is declared under `tool.poetry.extras` with the same name as your module name,
     we still prefer adding _NO EXTRA DEPENDENCIES_, meaning `mymodule = []` is the preferred addition
     (see the notes at the bottom)
-- [ ] The `INDEX.rst` at the project root includes your module under the `.. toctree` directive
-- [ ] Your branch is up to date (or we'll use GH's "update branch" function through the UI)
+- [ ] Your branch is up-to-date (or your branch will be rebased with `git rebase`)
 
 # Preferred implementation
 

diff --git a/index.rst b/index.rst
@@ -13,6 +13,7 @@ testcontainers-python
 testcontainers-python facilitates the use of Docker containers for functional and integration testing. The collection of packages currently supports the following features.
 
 .. toctree::
+    :maxdepth: 1
 
     core/README
     modules/index
@@ -59,12 +60,15 @@ Installation
 ------------
 
 The suite of testcontainers packages is available on `PyPI <https://pypi.org/project/testcontainers/>`_,
-and individual packages can be installed using :code:`pip`.
+the package can be installed using :code:`pip`.
 
-Version `4.0.0` onwards we do not support the `testcontainers-*` packages as it is unsutainable to maintain ownership.
+Version `4.0.0` onwards we do not support the `testcontainers-*` packages as it is unsustainable to maintain ownership.
 
 Instead packages can be installed by specifying `extras <https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies>`__, e.g., :code:`pip install testcontainers[postgres]`.
 
+Please note, that community modules are supported on a best-effort basis and breaking changes DO NOT create major versions in the package.
+Therefore, only the package core is strictly following SemVer. If your workflow is broken by a minor update, please look at the changelogs for guidance.
+
 
 Custom Containers
 -----------------
@@ -80,40 +84,77 @@ For common use cases, you can also use the generic containers provided by the `t
 Docker in Docker (DinD)
 -----------------------
 
-When trying to launch a testcontainer from within a Docker container, e.g., in continuous integration testing, two things have to be provided:
+When trying to launch Testcontainers from within a Docker container, e.g., in continuous integration testing, two things have to be provided:
 
 1. The container has to provide a docker client installation. Either use an image that has docker pre-installed (e.g. the `official docker images <https://hub.docker.com/_/docker>`_) or install the client from within the `Dockerfile` specification.
 2. The container has to have access to the docker daemon which can be achieved by mounting `/var/run/docker.sock` or setting the `DOCKER_HOST` environment variable as part of your `docker run` command.
 
+
+Private Docker registry
+-----------------------
+
+Using a private docker registry requires the `DOCKER_AUTH_CONFIG` environment variable to be set.
+`official documentation <https://docs.docker.com/engine/reference/commandline/login/#credential-helpers>`_
+
+The value of this variable should be a JSON string containing the authentication information for the registry.
+
+Example:
+
+.. code-block:: bash
+
+    DOCKER_AUTH_CONFIG='{"auths": {"https://myregistry.com": {"auth": "dXNlcm5hbWU6cGFzc3dvcmQ="}}}'
+
+In order to generate the JSON string, you can use the following command:
+
+.. code-block:: bash
+
+    echo -n '{"auths": {"<url>": {"auth": "'$(echo -n "<username>:<password>" | base64 -w 0)'"}}}'
+
+Fetching passwords from cloud providers:
+
+.. code-block:: bash
+
+    ECR_PASSWORD = $(aws ecr get-login-password --region eu-west-1)
+    GCP_PASSWORD = $(gcloud auth print-access-token)
+    AZURE_PASSWORD = $(az acr login --name <registry-name> --expose-token --output tsv)
+
+
 Configuration
 -------------
 
-+-------------------------------------------+-------------------------------+------------------------------------------+
-| Env Variable                              | Example                       | Description                              |
-+===========================================+===============================+==========================================+
-| ``TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE`` | ``/var/run/docker.sock``      | Path to Docker's socket used by ryuk     |
-+-------------------------------------------+-------------------------------+------------------------------------------+
-| ``TESTCONTAINERS_RYUK_PRIVILEGED``        | ``false``                     | Run ryuk as a privileged container       |
-+-------------------------------------------+-------------------------------+------------------------------------------+
-| ``TESTCONTAINERS_RYUK_DISABLED``          | ``false``                     | Disable ryuk                             |
-+-------------------------------------------+-------------------------------+------------------------------------------+
-| ``RYUK_CONTAINER_IMAGE``                  | ``testcontainers/ryuk:0.7.0`` | Custom image for ryuk                    |
-+-------------------------------------------+-------------------------------+------------------------------------------+
++-------------------------------------------+---------------------------------------------------+------------------------------------------+
+| Env Variable                              | Example                                           | Description                              |
++===========================================+===================================================+==========================================+
+| ``TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE`` | ``/var/run/docker.sock``                          | Path to Docker's socket used by ryuk     |
++-------------------------------------------+---------------------------------------------------+------------------------------------------+
+| ``TESTCONTAINERS_RYUK_PRIVILEGED``        | ``false``                                         | Run ryuk as a privileged container       |
++-------------------------------------------+---------------------------------------------------+------------------------------------------+
+| ``TESTCONTAINERS_RYUK_DISABLED``          | ``false``                                         | Disable ryuk                             |
++-------------------------------------------+---------------------------------------------------+------------------------------------------+
+| ``RYUK_CONTAINER_IMAGE``                  | ``testcontainers/ryuk:0.7.0``                     | Custom image for ryuk                    |
++-------------------------------------------+---------------------------------------------------+------------------------------------------+
+| ``DOCKER_AUTH_CONFIG``                    | ``{"auths": {"<url>": {"auth": "<encoded>"}}}``   | Custom registry auth config              |
++-------------------------------------------+---------------------------------------------------+------------------------------------------+
 
 Development and Contributing
 ----------------------------
 
-We recommend you use a `virtual environment <https://virtualenv.pypa.io/en/stable/>`_ for development (:code:`python>=3.7` is required). After setting up your virtual environment, you can install all dependencies and test the installation by running the following snippet.
+
+We recommend you use a `Poetry <https://python-poetry.org/docs/>`_ for development.
+After having installed `poetry`, you can run the following snippet to set up your local dev environment.
 
 .. code-block:: bash
 
-    poetry install --all-extras
-    make <your-module>/tests
+    make install
 
 Package Structure
 ^^^^^^^^^^^^^^^^^
 
-Testcontainers is a collection of `implicit namespace packages <https://peps.python.org/pep-0420/>`__ to decouple the development of different extensions, e.g., :code:`testcontainers-mysql` and :code:`testcontainers-postgres` for MySQL and PostgreSQL database containers, respectively. The folder structure is as follows.
+Testcontainers is a collection of `implicit namespace packages <https://peps.python.org/pep-0420/>`__
+to decouple the development of different extensions,
+e.g., :code:`testcontainers[mysql]` and :code:`testcontainers[postgres]` for MySQL and PostgreSQL database containers, respectively.
+
+The folder structure is as follows:
 
 .. code-block:: bash
 
@@ -133,10 +174,11 @@ Testcontainers is a collection of `implicit namespace packages <https://peps.pyt
               ...
           # README for this feature.
           README.rst
-          # Setup script for this feature.
-          setup.py
 
 Contributing a New Feature
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-You want to contribute a new feature or container? Great! You can do that in six steps as outlined `here <https://github.com/testcontainers/testcontainers-python/blob/main/.github/PULL_REQUEST_TEMPLATE/new_container.md>__`.
+You want to contribute a new feature or container? Great!
+- We recommend you first `open an issue <https://github.com/testcontainers/testcontainers-python/issues/new/choose>`_
+- Then follow the suggestions from the team
+- We also have a Pull Request `template <https://github.com/testcontainers/testcontainers-python/blob/main/.github/PULL_REQUEST_TEMPLATE/new_container.md>`_ for new containers!