From 182121794de4714d3387fbca0dde5eb91c189334 Mon Sep 17 00:00:00 2001 From: Roman Lutz Date: Wed, 21 Feb 2024 15:46:08 -0800 Subject: [PATCH 1/6] Add release instructions --- doc/contributing.md | 39 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/doc/contributing.md b/doc/contributing.md index aa73b2406..1ed9238b7 100644 --- a/doc/contributing.md +++ b/doc/contributing.md @@ -156,4 +156,41 @@ PyRIT test files can be run using `pytest`. ## Releasing PyRIT to PyPI -TODO +Create an account on pypi.org if you don't have one yet. +Ask one of the other maintainers to add you to the `pyrit` project on PyPI. + +Make sure the version data in pyproject.toml is set correctly. +We use standard versioning for Python. +Below, we use x.y.z as the example version. + +Before running the following command replace all "local" links like +"./doc/README.md" with links that will work from any website, i.e., +"https://github.com/Azure/PyRIT/blob/release/vx.y.z/doc/README.md" + +Commit your changes and push them to the repository on a branch called +`release/vx.y.z`, then run + +```bash +git tag -a vx.y.z -m "vx.y.z release" +git push --tags +``` + +To build the package wheel and archive for PyPI run + +```bash +python -m build +``` + +This should print + +> Successfully built pyrit-x.y.z.tar.gz and pyrit-x.y.z-py3-none-any.whl + +```bash +pip install twine +twine upload dist/* +``` + +If successful, it will print + +> View at: + https://pypi.org/project/pyrit/x.y.z/ From 883f69c34016e8d8efe282fd0cd2629544a67466 Mon Sep 17 00:00:00 2001 From: Roman Lutz Date: Wed, 21 Feb 2024 15:56:52 -0800 Subject: [PATCH 2/6] fix release branch name --- doc/contributing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/contributing.md b/doc/contributing.md index 1ed9238b7..5dcb92b89 100644 --- a/doc/contributing.md +++ b/doc/contributing.md @@ -165,10 +165,10 @@ Below, we use x.y.z as the example version. Before running the following command replace all "local" links like "./doc/README.md" with links that will work from any website, i.e., -"https://github.com/Azure/PyRIT/blob/release/vx.y.z/doc/README.md" +"https://github.com/Azure/PyRIT/blob/releases/vx.y.z/doc/README.md" Commit your changes and push them to the repository on a branch called -`release/vx.y.z`, then run +`releases/vx.y.z`, then run ```bash git tag -a vx.y.z -m "vx.y.z release" From 628e94a6466b2761a1340447925f565b161d1c7c Mon Sep 17 00:00:00 2001 From: Roman Lutz Date: Wed, 21 Feb 2024 16:15:20 -0800 Subject: [PATCH 3/6] add note on versioning and syncing version numbers --- doc/contributing.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/contributing.md b/doc/contributing.md index 5dcb92b89..6faf8207b 100644 --- a/doc/contributing.md +++ b/doc/contributing.md @@ -160,6 +160,9 @@ Create an account on pypi.org if you don't have one yet. Ask one of the other maintainers to add you to the `pyrit` project on PyPI. Make sure the version data in pyproject.toml is set correctly. +Keep that version in sync with `__init__.py` which is usually set to +the next version (e.g., x.y.z+1) with suffix `.dev0`. +For the release branch, we can remove this suffix. We use standard versioning for Python. Below, we use x.y.z as the example version. @@ -194,3 +197,7 @@ If successful, it will print > View at: https://pypi.org/project/pyrit/x.y.z/ + +Finally, make sure to create a PR for the `main` branch where the only change +is the version increase in `__init__.py` (while keeping suffix `.dev0`). +This should be something like `x.y.z+1.dev0`. From 0716313bd75aa6cf399a828c1996bc3853288cb2 Mon Sep 17 00:00:00 2001 From: Roman Lutz Date: Mon, 26 Feb 2024 22:29:32 -0800 Subject: [PATCH 4/6] update with PR feedback --- doc/contributing.md | 48 +++++++++++++++++++++++++++++++++++++-------- 1 file changed, 40 insertions(+), 8 deletions(-) diff --git a/doc/contributing.md b/doc/contributing.md index 5a17ca644..a4eb11a54 100644 --- a/doc/contributing.md +++ b/doc/contributing.md @@ -191,19 +191,48 @@ PyRIT test files can be run using `pytest`. ## Releasing PyRIT to PyPI -Create an account on pypi.org if you don't have one yet. -Ask one of the other maintainers to add you to the `pyrit` project on PyPI. +This section is for maintainers only. +If you don't know who the maintainers are but you need to reach them +please file an issue or (if it needs to remain private) contact the +email address listed in pyproject.toml + +First, decide what the next release version is going to be. +We follow semantic versioning for Python projects; see +https://semver.org/ for more details. +Below, we refer to the version as `x.y.z`. +`x` is the major version, `y` the minor version, and `z` the patch version. +Every Python project starts at `0.1.0`. +Patches such as bugfixes without breaking changes increase the patch version. +Importantly, they are backward compatible, so upgrading from `0.1.0` to +`0.1.1` (or higher ones like `0.1.38`) should not break your code. +More significant changes such as major features. +They should still be backwards compatible, so if you're upgrading from +`1.1.0` to `1.2.0` your code shouldn't break. +In reality, the major version `1.0.0` is the first "stable" release. +Anything before (i.e., leading with major version `0`) indicates that it is +not stable and anything may change at any time. +For that reason, we the minor version may indicate breaking changes, too, +at least until we hit major version `1`. + +With that in mind, the reason for the release and the set of changes +that happened since the last release will influence the new version number. Make sure the version data in pyproject.toml is set correctly. Keep that version in sync with `__init__.py` which is usually set to -the next version (e.g., x.y.z+1) with suffix `.dev0`. -For the release branch, we can remove this suffix. -We use standard versioning for Python. -Below, we use x.y.z as the example version. +the next planned version with suffix `.dev0`. +This makes it easier to distinguish versions when someone submits a bug +as we will be able to tell if it's a release version or dev version. +For the release branch, we have to remove this suffix. Before running the following command replace all "local" links like "./doc/README.md" with links that will work from any website, i.e., -"https://github.com/Azure/PyRIT/blob/releases/vx.y.z/doc/README.md" +"https://github.com/Azure/PyRIT/blob/releases/vx.y.z/doc/README.md". +For images, the past releases didn't succeed in getting them to render. +For the next release, let's try and modify the image links to the "raw" +link, e.g., +"https://raw.githubusercontent.com/Azure/PyRIT/releases/vx.y.z/assets/pyrit_architecture.png". +This is required for the release branch because PyPI does not pick up +other files besides the README, which results in local links breaking. Commit your changes and push them to the repository on a branch called `releases/vx.y.z`, then run @@ -219,10 +248,13 @@ To build the package wheel and archive for PyPI run python -m build ``` -This should print +This should print > Successfully built pyrit-x.y.z.tar.gz and pyrit-x.y.z-py3-none-any.whl +Create an account on pypi.org if you don't have one yet. +Ask one of the other maintainers to add you to the `pyrit` project on PyPI. + ```bash pip install twine twine upload dist/* From 6b043832f5664eb7d6c0b716267707d667988228 Mon Sep 17 00:00:00 2001 From: Roman Lutz Date: Wed, 28 Feb 2024 10:30:00 -0800 Subject: [PATCH 5/6] update based on Nina's feedback --- doc/contributing.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/contributing.md b/doc/contributing.md index a4eb11a54..a289e29ab 100644 --- a/doc/contributing.md +++ b/doc/contributing.md @@ -205,13 +205,14 @@ Every Python project starts at `0.1.0`. Patches such as bugfixes without breaking changes increase the patch version. Importantly, they are backward compatible, so upgrading from `0.1.0` to `0.1.1` (or higher ones like `0.1.38`) should not break your code. -More significant changes such as major features. +More significant changes, such as major features, require at least a new +minor version. They should still be backwards compatible, so if you're upgrading from `1.1.0` to `1.2.0` your code shouldn't break. -In reality, the major version `1.0.0` is the first "stable" release. +The major version `1.0.0` is the first "stable" release. Anything before (i.e., leading with major version `0`) indicates that it is not stable and anything may change at any time. -For that reason, we the minor version may indicate breaking changes, too, +For that reason, the minor version may indicate breaking changes, too, at least until we hit major version `1`. With that in mind, the reason for the release and the set of changes From 290fa94601db5e72c4ed8616a5d2557ffd9dd07e Mon Sep 17 00:00:00 2001 From: Roman Lutz Date: Wed, 28 Feb 2024 15:08:58 -0800 Subject: [PATCH 6/6] address Christian's PR comment --- doc/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing.md b/doc/contributing.md index a289e29ab..7f75410ec 100644 --- a/doc/contributing.md +++ b/doc/contributing.md @@ -202,7 +202,7 @@ https://semver.org/ for more details. Below, we refer to the version as `x.y.z`. `x` is the major version, `y` the minor version, and `z` the patch version. Every Python project starts at `0.1.0`. -Patches such as bugfixes without breaking changes increase the patch version. +Backwards compatible bug fixes increase the patch version. Importantly, they are backward compatible, so upgrading from `0.1.0` to `0.1.1` (or higher ones like `0.1.38`) should not break your code. More significant changes, such as major features, require at least a new