docs(contributing): add contribution and new-container guide

[totallyzen]

change

Document how to contribute, with initial focus on making local development smooth.

Tasks

• [x] Finish the new-container guide
• [x] Remove any old docs referring to
• [x] Update README.md to point at the contribution guide
• [x] Update README.md to add badges (supported python versions, etc) and to give kudos to current and past maintainers and contributors

[totallyzen]

@jankatins @bearrito @max-pfeiffer your comments are very welcome - It's still in draft, but it's a start!

This is what I had time for today, but will continue on the weekday evenings!

[totallyzen]

@santi also, this will be useful for you!

[alexanderankin]

looks good to me, i find this stuff very valuable but right now i dont really know what to add as far as suggestions or discussion. my head is mostly in the outstanding PRs and releases and such.

also sorry for the double rebase. i did a rebase locally onto main. then i found a button on github, but the button on github gave me credit for all your work, so then i just pushed my local rebase.

[alexanderankin]

it might also make sense to capture what it takes to implement a new container, not just request one

[alexanderankin]

quick summary of how to test buildthedocs changes:

1. make a new project on buildthedocs
2. "import" your fork of this repository
3. push changes and test there
   1. significant files: /.readthedocs.yml, /Makefile (the make docs target, specifically), /conf.py (the sphinx stuff), /docs/_build (preview the result locally)
4. then open pr here

[max-pfeiffer]

it might also make sense to capture what it takes to implement a new container, not just request one

Yes, I think so too. We could briefly elaborate about the best practices that we want to see in contributions. So modules are a bit more consistent.

Maybe also what to include in README.rst in the modules directory. To me it's not clear what purpose that serves currently.

[max-pfeiffer]

I would say also our .pre-commit-config.yaml also needs some attention: there we have black for code formatting and ruff as linter defined. What about just using ruff? ruff can format code as well and is pretty fast in doing that. Then we can drop that black dependency.

I like badges :smiley:. So would could add the following badges:

• Poetry
• ruff
• supported Python versions
• pipeline status
• test coverage Codecov, see my comment on the make file for running tests with pytest-cov

@totallyzen Can I add commits to this PR? Then I could quickly contribute my suggestions.

[totallyzen]

Can I add commits to this PR? Then I could quickly contribute my suggestions.

Yes, please do! Including the black -> ruff transition as long as it doesn't reformat the entire repo :slightly_smiling_face: If we are to improve/fix formatting, I want that to be in another PR.

@bearrito actually, I think given my lack of time lately, you could contribute the devcontainers setup to this PR as well, just ping the request on this PR as well so I can track :pray:

[jankatins]

Including the black -> ruff transition as long as it doesn't reformat the entire repo 🙂

Ruff is compatible with black apart from a very few and rare differences. I've several repos here where black and ruff format are interchangeable :-)

[bearrito]

@totallyzen I can do that. It will either be today or tomorrow. Likely tomorrow.

[bearrito]

@totallyzen Can I get this approved if it looks okay- https://github.com/testcontainers/testcontainers-python/pull/506 Namely I want to be able to reference that work in the docs for devcontainers

[MattOates]

As someone who just tried to raise a PR with a new container, and just checked out these new docs. Can I point out its not obvious at all on these points:

.github/workflows/main.yml to run tests, build, and publish your package when pushed to the main branch.

No such file exists.

Rebase your development branch on main (or merge main into your development branch).

Main just changed whilst I've had my PR up, is the preference I rebase and force push over the top of my already published PR constantly?

Add a line -e file:[feature name] to requirements.in

Where is requirements.in ??? If you add directly to pyproject.toml under a module is this sufficient and correct?

[totallyzen]

Hey @MattOates,

Thanks for the pointers, I'm sorry for your bad experience, but please note that this PR is a draft, I did not have time to finish it. A lot of people left comments on it, all duly noted, you can in fact raise a PR against this branch and make suggestions. :+1: You can also keep your calm about it, the current maintainers are volunteers, with sometimes very little time to spare on this. :+1:

[totallyzen]

@bearrito done, I merged #506 - feel free to reference it in your next PR :pray:

Apologies for the continued delays, my work weeks have been intense/depressing/exhausting. :bow:

[santi]

Hey @MattOates sorry for your rough start here, but we really appreciate you contributions 😊 Hopefully the latest additions to the draft should make clear the things you are wondering about.

We have just revamped the whole structure and development setup in this repo, so no wonder the docs are very outdated. I hope you stay and find the new setup easier to work with 😀

[max-pfeiffer]

Can I add commits to this PR? Then I could quickly contribute my suggestions.

@totallyzen I just created this PR containing some badges: https://github.com/testcontainers/testcontainers-python/pull/528

I also picked up communications with @kiview on Slack to make code coverage reports and that codecov.io badge happen.

[max-pfeiffer]

Yes, please do! Including the black -> ruff transition as long as it doesn't reformat the entire repo 🙂 If we are to improve/fix formatting, I want that to be in another PR.

@totallyzen I just created a PR and removed that black dependency: https://github.com/testcontainers/testcontainers-python/pull/529

Just a couple of files became re-formatted. So this we have rather little code changes.

[totallyzen]

I'll merge this, I heard no negative comments on the existing additions and some improvements rely on main -> let's consider this PR to be "done"

[alexanderankin]

lgtm!

[MattOates]

Hey @MattOates sorry for your rough start here, but we really appreciate you contributions 😊 Hopefully the latest additions to the draft should make clear the things you are wondering about.

Apologies if that came across as brusk, if I did know anything about the desired dev setup I'd absolutely help dig in. I just cargo culted my way to a PR and just wanted to point out the draft still had some rabbit holes for someone coming cold. Is there a shaping doc anywhere of where the project is headed for dev experience?

[alexanderankin]

this branch is now rebased

~~if someone wants to help out - let me know if you see any glaring differences between these two pages:~~

~~https://github.com/testcontainers/testcontainers-python/compare/main..docs/improve-contribution-guide.tmp~~

~~- this is the rebased version of this PR - it needs the committer reset to the author and force pushed to this branch~~

~~https://github.com/testcontainers/testcontainers-python/compare/main...docs/improve-contribution-guide~~

~~- this is a simplified view of the files tab on this page~~