Skip to content

docs: align contributor Python version docs with package metadata #9047

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

Open
immanuwell wants to merge 2 commits into
base: develop
Choose a base branch
from
+30 −30
Open

docs: align contributor Python version docs with package metadata #9047

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1c3f021
docs: align contributor Python version guidance
immanuwell May 25, 2026
c9cc494
docs: fix stale virtualenv example in dev guide
immanuwell May 25, 2026
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
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Contributions via pull requests are much appreciated. Before sending us a pull r
1. You are working against the latest source on the *develop* branch.
2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
3. You open an issue to discuss any significant work - we would hate for your time to be wasted.
4. The change works in Python3 (see supported Python Versions in setup.py)
4. The change works in supported Python versions (see `pyproject.toml` and CI workflows)
5. Does the PR have updated/added unit, functional, and integration tests?
6. PR is merged submitted to merge into develop.

Expand Down
58 changes: 29 additions & 29 deletions DEVELOPMENT_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Gitpod is free for 50 hours per month - make sure to stop your workspace when yo
## Environment Setup
### 1. Prerequisites (Python Virtual Environment)

AWS SAM CLI is mainly written in Python 3 and we support Python 3.8 and above.
AWS SAM CLI is mainly written in Python 3 and currently requires Python 3.10 and above.
So, having a Python environment with this version is required.

Having a dedicated Python virtual environment ensures it won't "pollute" or get "polluted"
Expand Down Expand Up @@ -64,10 +64,10 @@ exec $SHELL # restart your shell to enable pyenv-virtualenv
Next, setup a virtual environment and activate it:

```sh
# Assuming you want to develop AWS SAM CLI in Python 3.8.9
pyenv install 3.8.9 # install Python 3.8.9 using pyenv
pyenv virtualenv 3.8.9 samcli38 # create a virtual environment using 3.8.9 named "samcli38"
pyenv activate samcli38 # activate the virtual environment
# Assuming you want to develop AWS SAM CLI in Python 3.10.19
pyenv install 3.10.19 # install Python 3.10.19 using pyenv
pyenv virtualenv 3.10.19 samcli310 # create a virtual environment using 3.10.19 named "samcli310"
pyenv activate samcli310 # activate the virtual environment
Copy link
Copy Markdown
Collaborator

@aws-sam-cli-bot aws-sam-cli-bot May 25, 2026

Choose a reason for hiding this comment

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

[GENERAL] The rename of the example virtualenv from samcli38 to samcli310 is incomplete. Line 145 in the "Install development version of SAM Transformer" section still reads:

pyenv activate samcli38  # if you chose to use pyenv to setup the virtual environment

After this PR, the prerequisites section instructs contributors to create a virtual environment named samcli310, so a reader who follows the new guide top-to-bottom will be told here to activate samcli38, which they were never instructed to create. Since this PR's stated goal is to align contributor docs with the current Python version, this leftover reference should be updated to samcli310 (and the surrounding sentence checked for any other stale Python 3.8/3.9 wording) for consistency.

Copy link
Copy Markdown
Author

@immanuwell immanuwell May 25, 2026

Choose a reason for hiding this comment

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

Fixed. I updated the leftover pyenv activate samcli38 example to samcli310 and re-checked the surrounding contributor-doc references for other stale Python 3.8/3.9 env names.

```

### 2. Initialize dependencies and create `samdev` available in `$PATH`
Expand Down Expand Up @@ -142,7 +142,7 @@ Make sure you are in the same virtual environment as the one you are using with
```sh
source <sam-cli-directory-path>/.venv/bin/activate # if you chose to use venv to setup the virtual environment
# or
pyenv activate samcli38 # if you chose to use pyenv to setup the virtual environment
pyenv activate samcli310 # if you chose to use pyenv to setup the virtual environment
```

Install the SAM Transformer in editable mode so that
Expand Down Expand Up @@ -173,27 +173,27 @@ contribute to the repository, there are a few more things to consider.

### Make Sure AWS SAM CLI Work in Multiple Python Versions

We support version 3.8 and above. Our CI/CD pipeline is setup to run
unit tests against all Python versions. So make sure you test it
with all versions before sending a Pull Request.
We support version 3.10 and above. Our PR workflow runs on Python 3.10 and 3.11,
and our integration workflows install additional Python versions to cover Lambda runtime scenarios.
So make sure you test your change against supported Python versions before sending a Pull Request.
See [Unit testing with multiple Python versions](#unit-testing-with-multiple-python-versions-optional).
This is most important if you are developing in a Python version greater than the minimum supported version (currently 3.8), as any new features released in 3.9+ will not work.
This is most important if you are developing in a Python version greater than the minimum supported version (currently 3.10), as any new features released in higher versions will not work on the minimum supported version.

If you chose to use `pyenv` in the previous session, setting up a
different Python version should be easy:

(assuming you are in virtual environment named `samcli39` with Python version 3.9.x)
(assuming you are in virtual environment named `samcli311` with Python version 3.11.x)

```sh
# Your shell now should look like "(samcli39) $"
pyenv deactivate samcli39 # "(samcli39)" will disappear
pyenv install 3.8.9 # one time setup
pyenv virtualenv 3.8.9 samcli38 # one time setup
pyenv activate samcli38
# Your shell now should look like "(samcli38) $"
# Your shell now should look like "(samcli311) $"
pyenv deactivate samcli311 # "(samcli311)" will disappear
pyenv install 3.10.19 # one time setup
pyenv virtualenv 3.10.19 samcli310 # one time setup
pyenv activate samcli310
# Your shell now should look like "(samcli310) $"

# You can verify the version of Python
python --version # Python 3.8.9
python --version # Python 3.10.19

make init # one time setup, this will put a file `samdev` available in $PATH
```
Expand All @@ -202,8 +202,8 @@ For Windows, use your favorite tool for managing different python versions and e

### Format Python Code

We format our code using [Black](https://github.com/python/black) and verify the source code is
black compliant in AppVeyor during PRs. Black will be installed automatically with `make init` or `./Make -Init` on Windows.
We format our code using [Black](https://github.com/python/black) and verify the source code in GitHub Actions during PRs.
Black will be installed automatically with `make init` or `./Make -Init` on Windows.

There are generally 3 options to make sure your change is compliant with our formatting standard:

Expand Down Expand Up @@ -235,11 +235,11 @@ and this will happen:
pyenv: black: command not found

The `black' command exists in these Python versions:
3.8.9/envs/samcli38
samcli38
3.10.19/envs/samcli310
samcli310
```

A simple workaround is to use `/Users/<username>/.pyenv/versions/samcli37/bin/black`
A simple workaround is to use `/Users/<username>/.pyenv/versions/samcli310/bin/black`
instead of `/Users/<username>/.pyenv/shims/black`.

#### (Option 3) Pre-commit
Expand All @@ -265,12 +265,12 @@ We also suggest to run `make pr` or `./Make -pr` in all Python versions.

#### Unit Testing with Multiple Python Versions (Optional)

Currently, SAM CLI only supports Python3 versions (see setup.py for exact versions). For the most
part, code that works in Python3.8 will work in Python3.9. You only run into problems if you are
trying to use features released in a higher version (for example features introduced into Python3.9
will not work in Python3.8). If you want to test in many versions, you can create a virtualenv for
each version and flip between them (sourcing the activate script). Typically, we run all tests in
one python version locally and then have our ci (appveyor) run all supported versions.
Currently, SAM CLI supports Python 3.10 and above (see `pyproject.toml` for package metadata and
`.github/workflows/build.yml` for the PR test matrix). For the most part, code that works in Python 3.10
will work in Python 3.11. You only run into problems if you are trying to use features released in a
higher version that do not exist in the minimum supported version. If you want to test in many versions,
you can create a virtualenv for each version and flip between them (sourcing the activate script).
Typically, we run tests in one Python version locally and let CI cover the supported matrix.

#### Integration Test (Optional)

Expand Down