Document IDE setup

Nobody has claimed this yet.

tl;dr

I propose an IDE-setup section under Developer Setup.

How to connect to your running Docker dev container (recommended)
- type of IDE
- extension suggestions
- troubleshooting
How to use uv and venv locally (maybe hacky, not recommended)
solve the psycopg2 situation?
- Another bug? Do we need to build it ourselves or may psycopg2-binary be good enough?
- (While at it might also be worth to look into Psycopg 3, seems 2 is being phased out.)
have a make command to setup the IDE stuff in place?
- for docker and/or local setup

whole story

I was browsing the Developer Setup docs but didn't find anything to help with navigating/debugging the project in the IDE.

Since I'm on Codium the ms Dev Containers extension didn't work. There are alternatives such as DevPod Containers but they require a devcontainer.json and I actually don't know yet if this is the preferred way of doing things?

And since I "just"™ wanted the red squiggly lines to go away first and uv is already in use here I looked into the .python-version file and ran

uv venv --python 3.13

and then

uv pip install \
  -r requirements/default.txt \
  -r requirements/dev.txt \
  -r requirements/test.txt \
  -r requirements/lint.txt

which threw this error at me:

Error: pg_config executable not found.

× Failed to build `psycopg2==2.9.12`
  ├─▶ The build backend returned an error
  ╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)

      [stdout]
      running egg_info
      writing psycopg2.egg-info/PKG-INFO
      writing dependency_links to psycopg2.egg-info/dependency_links.txt
      writing top-level names to psycopg2.egg-info/top_level.txt

      [stderr]
      /Users/ewerner/.cache/uv/builds-v0/.tmp8ejsGl/lib/python3.13/site-packages/setuptools/dist.py:765:
      SetuptoolsDeprecationWarning: License classifiers are deprecated.
      !!

              ********************************************************************************
              Please consider removing the following classifiers in favor of a SPDX license
      expression:

              License :: OSI Approved :: GNU Library or Lesser General Public License
      (LGPL)

              See
      https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#license for
      details.
              ********************************************************************************

      !!
        self._finalize_license_expression()

      Error: pg_config executable not found.

      pg_config is required to build psycopg2 from source.  Please add the directory
      containing pg_config to the $PATH or specify the full executable path with the
      option:

          python setup.py build_ext --pg-config /path/to/pg_config build ...

      or with the pg_config option in 'setup.cfg'.

      If you prefer to avoid building psycopg2 from source, please install the PyPI
      'psycopg2-binary' package instead.

      For further information please check the 'doc/src/install.rst' file (also at
      <https://www.psycopg.org/docs/install.html>).



hint: Build failures usually indicate a problem with the package or the build environment%

Fair enough that's "documented" here:
https://github.com/mozilla/pontoon/blob/bfe34e1e06d2d965cf52226292ee39c446e2f7db/docker/Dockerfile-mozcloud#L11-L12

So I would either need to:

get the same libpq-dev package additionally or install Postgres.app for mac or something else on other systems to have the requirements to build this package OR
hack the requirements/default.in to say psycopg2-binary==2.9.12
- run make requirements
- retry uv pip install ...

Long story short: I wish we had Dev IDE setup in the docs! OK, let me wrap this up in a tl;dr ...

Start with documentation/docs/dev/developer-setup.md, then compare docker/Dockerfile-mozcloud and requirements/default.in. Document IDE workflows for Docker and local uv/venv setup, including the psycopg2 prerequisite decision and any make setup command. Done means the setup steps and troubleshooting guidance are usable.

Written by the indexing model from the issue text.

Description

tl;dr

whole story

Contributor guide

First steps

Research direction

Assessment

Document IDE setup

Description

tl;dr

whole story

Contributor guide

First steps

Research direction

Assessment

Get new issues in your inbox