Skip to content

Commit 4ea92ec

Browse files
codejedi365codejedi365
committed
docs(upgrading-v10): added migration guide for v9 to v10
1 parent 8bed5bc commit 4ea92ec

File tree

2 files changed

+190
-0
lines changed

2 files changed

+190
-0
lines changed

‎docs/upgrading/10-upgrade.rst

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
.. _upgrade_v10:
2+
3+
Upgrading to v10
4+
================
5+
6+
The upgrade to v10 is primarily motivated by a command injection security vulnerability
7+
found in the GitHub Actions configuration interpreter (see details
8+
:ref:`below <upgrade_v10-root_options>`). We also bundled a number of other changes,
9+
including new default configuration values and most importantly, a return to 1-line
10+
commit subjects in the default changelog format.
11+
12+
For more specific change details for v10, please refer to the :ref:`changelog-v10.0.0`
13+
section of the :ref:`changelog`.
14+
15+
16+
.. _upgrade_v10-root_options:
17+
18+
Security Fix: Command Injection Vulnerability (GitHub Actions)
19+
--------------------------------------------------------------
20+
21+
In the previous versions of the GitHub Actions configuration, we used a single
22+
``root_options`` parameter to pass any options you wanted to pass to the
23+
``semantic-release`` main command. This parameter was interpreted as a string and
24+
passed directly to the command line, which made it vulnerable to command injection
25+
attacks. An attacker could exploit this by crafting a malicious string as the
26+
:ref:`gh_actions-psr-inputs-root_options` input, and then it would be executed
27+
as part of the command line, potentially allowing them to run arbitrary commands within
28+
the GitHub Actions Docker container. The ability to exploit this vulnerability is limited
29+
to people whom can modify the GitHub Actions workflow file, which is typically only the
30+
repository maintainers unless you are pointing at an organizational workflow file or
31+
another third-party workflow file.
32+
33+
To mitigate this vulnerability, we have removed the ``root_options`` parameter completely
34+
and replaced it with individual boolean flag inputs which are then used to select the proper
35+
cli parameters for the ``semantic-release`` command. Additionally, users can protect themselves
36+
by limiting the access to secrets in their GitHub Actions workflows and the permissions of
37+
the GitHub Actions CI TOKEN.
38+
39+
This vulnerability existed in both the
40+
:ref:`python-semantic-release/python-semantic-release <gh_actions-psr>` and
41+
:ref:`python-semantic-release/publish-action <gh_actions-publish>` actions.
42+
43+
For the main :ref:`python-semantic-release/python-semantic-release <gh_actions-psr>` action,
44+
the following inputs are now available (in place of the old ``root_options`` parameter):
45+
46+
- :ref:`gh_actions-psr-inputs-config_file`
47+
- :ref:`gh_actions-psr-inputs-noop`
48+
- :ref:`gh_actions-psr-inputs-strict`
49+
- :ref:`gh_actions-psr-inputs-verbosity`
50+
51+
For the :ref:`python-semantic-release/publish-action <gh_actions-publish>` action,
52+
the following inputs are now available (in place of the old ``root_options`` parameter):
53+
54+
- :ref:`gh_actions-publish-inputs-config_file`
55+
- :ref:`gh_actions-publish-inputs-noop`
56+
- :ref:`gh_actions-publish-inputs-verbosity`
57+
58+
59+
.. _upgrade_v10-changelog_format-1_line_commit_subjects:
60+
61+
Changelog Format: 1-Line Commit Subjects
62+
----------------------------------------
63+
64+
In v10, the default changelog format has been changed to use 1-line commit subjects instead of
65+
including the full commit message. This change was made to improve the readability of the changelog
66+
as many commit messages are long and contain unnecessary details for the changelog.
67+
68+
.. important::
69+
If you use a squash commit merge strategy, it is recommended that you use the default
70+
``parse_squash_commits`` commit parser option to ensure that all the squashed commits are
71+
parsed for version bumping and changelog generation. This is the default behavior in v10 across
72+
all supported commit parsers. If you are upgrading, you likely will need to manually set this
73+
option in your configuration file to ensure that the changelog is generated correctly.
74+
75+
If you do not enable ``parse_squash_commits``, then version will only be determined by the
76+
commit subject line and the changelog will only include the commit subject line as well.
77+
78+
79+
.. _upgrade_v10-changelog_format-mask_initial_release:
80+
81+
Changelog Format: Mask Initial Release
82+
--------------------------------------
83+
84+
In v10, the default behavior for the changelog generation has been changed to mask the initial
85+
release in the changelog. This means that the first release will not contain a break down of the
86+
different types of changes (e.g., features, fixes, etc.), but instead it will just simply state
87+
that this is the initial release.
88+
89+
90+
.. _upgrade_v10-changelog_format-commit_parsing:
91+
92+
Changelog Format: Commit Parsing
93+
--------------------------------
94+
95+
We have made some minor changes to the commit parsing logic in *v10* to
96+
separate out components of the commit message more clearly. You will find that the
97+
:py:class:`ParsedCommit <semantic_release.commit_parser.token.ParsedCommit>` object's
98+
descriptions list will no longer contain any Breaking Change footers, Release Notice footers,
99+
PR/MR references, or Issue Closure footers. These were all previously extracted and placed
100+
into their own attributes but were still included in the descriptions list. In *v10*,
101+
the descriptions list will only contain the actual commit subject line and any additional
102+
commit body text that is not part of the pre-defined footers.
103+
104+
If you were relying on the descriptions list to contain these footers, you will need to
105+
update your code and changelog templates to reference the specific attributes you want to use.
106+
107+
108+
.. _upgrade_v10-default_config:
109+
110+
Default Configuration Changes
111+
-----------------------------
112+
113+
The following table summarizes the changes to the default configuration values in v10:
114+
115+
.. list-table::
116+
:widths: 5 55 20 20
117+
:header-rows: 1
118+
119+
* - #
120+
- Configuration Option
121+
- Previous Default Value
122+
- New Default Value
123+
124+
* - 1
125+
- :ref:`config-allow_zero_version`
126+
- ``true``
127+
- ``false``
128+
129+
* - 2
130+
- :ref:`changelog.mode <config-changelog-mode>`
131+
- ``init``
132+
- ``update``
133+
134+
* - 3
135+
- :ref:`changelog.default_templates.mask_initial_release <config-changelog-default_templates-mask_initial_release>`
136+
- ``false``
137+
- ``true``
138+
139+
* - 4
140+
- :ref:`commit_parser_options.parse_squash_commits <config-commit_parser_options>`
141+
- ``false``
142+
- ``true``
143+
144+
* - 5
145+
- :ref:`commit_parser_options.ignore_merge_commits <config-commit_parser_options>`
146+
- ``false``
147+
- ``true``
148+
149+
150+
.. _upgrade_v10-deprecations:
151+
152+
Deprecations & Removals
153+
-----------------------
154+
155+
No additional deprecations were made in *v10*, but the following are staged
156+
for removal in v11:
157+
158+
.. list-table:: Deprecated Features & Functions
159+
:widths: 5 30 10 10 45
160+
:header-rows: 1
161+
162+
* - #
163+
- Component
164+
- Deprecated
165+
- Planned Removal
166+
- Notes
167+
168+
* - 1
169+
- :ref:`GitHub Actions root_options <gh_actions-psr-inputs-root_options>`
170+
- v10.0.0
171+
- v10.0.0
172+
- Replaced with individual boolean flag inputs. See :ref:`above <upgrade_v10-root_options>` for details.
173+
174+
* - 2
175+
- :ref:`Angular Commit Parser <commit_parser-builtin-angular>`
176+
- v9.19.0
177+
- v11.0.0
178+
- Replaced by the :ref:`Conventional Commit Parser <commit_parser-builtin-conventional>`.
179+
180+
* - 3
181+
- :ref:`Tag Commit Parser <commit_parser-builtin-tag>`
182+
- v9.12.0
183+
- v11.0.0
184+
- Replaced by the :ref:`Emoji Commit Parser <commit_parser-builtin-emoji>`.
185+
186+
.. note::
187+
For the most up-to-date information on the next version deprecations and removals, please
188+
refer to the issue
189+
`#1066 <https://github.com/python-semantic-release/python-semantic-release/issues/1066>`_.

‎docs/upgrading/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,5 +22,6 @@ versions of PSR to the latest version.
2222
:caption: Upgrade Guides
2323
:maxdepth: 1
2424

25+
Upgrading to v10 <10-upgrade>
2526
Upgrading to v9 <09-upgrade>
2627
Upgrading to v8 <08-upgrade>

0 commit comments

Comments
 (0)