diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..fdacd995 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,5 @@ +# Normalize line endings in the repository so the files are identical on every +# platform. This matters for CHANGELOG.rst: python-semantic-release looks for its +# insertion flag in that file, and it builds the flag with the line separator of the +# current platform. With CRLF in the working tree, the flag is not found on Linux. +* text=auto eol=lf diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..a56b68c7 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,8 @@ +# Lines starting with '#' are comments. +# Each line is a file pattern followed by one or more owners. + +# Default owners for everything in the repository. +# Only @Telefonica/toolium is listed on purpose: the code owner rule is used to +# guarantee that at least one approval comes from a member of that team. If a +# second team were added here, an approval from either team would satisfy it. +* @Telefonica/toolium diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..7d4b4d2d --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,30 @@ + + +## What does this change? + + + +## How was it tested? + + + +## Checklist + +- [ ] The **title of this pull request** follows the convention above +- [ ] `ruff check .` and `ruff format --check .` pass +- [ ] `python -m pytest` passes diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b67b26fa..2671ff32 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,6 +2,9 @@ name: build on: pull_request: + push: + branches: + - master jobs: python-versions: diff --git a/.github/workflows/release-test.yml b/.github/workflows/release-test.yml new file mode 100644 index 00000000..ece70448 --- /dev/null +++ b/.github/workflows/release-test.yml @@ -0,0 +1,108 @@ +name: release-test + +# Rehearses the release flow without touching PyPI, master or the real versioning. +# +# It can be started in two ways: +# - Manually, from the Actions tab (workflow_dispatch). GitHub only shows the button +# when this file exists on the default branch, so this path works after the first +# merge to master. +# - Pushing to a branch named test/*, which works before that first merge. +# +# The version is a prerelease (X.Y.Z-dev.N), so TestPyPI and PyPI never see a version +# that could be confused with a real release. The release commit and tag are created +# locally inside the run, but never pushed, so nothing lands in the repository: each run +# leaves the remote branches and tags untouched. + +on: + workflow_dispatch: + push: + branches: + - 'test/**' + +permissions: + contents: read + +# Sequential runs, so two rehearsals never race on the shared version calculation. +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: false + +jobs: + rehearsal: + name: Build prerelease and publish on TestPyPI + runs-on: ubuntu-latest + environment: + name: testpypi + url: https://test.pypi.org/p/toolium + permissions: + id-token: write # required for TestPyPI trusted publishing (OIDC) + steps: + - name: Checkout + uses: actions/checkout@v6 + with: + fetch-depth: 0 # semantic-release needs the full history and tags + token: ${{ secrets.GITHUB_TOKEN }} + - name: Set up python + uses: actions/setup-python@v6 + with: + python-version: '3.11' + - name: Install build dependencies + run: | + python -m pip install --upgrade pip + pip install build twine + - name: Calculate the next prerelease version + id: version + uses: python-semantic-release/python-semantic-release@v10 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + # The action requires the `commit_sha` output whenever a release happens, and + # python-semantic-release only sets it inside its tagging step. So a tag must be + # created locally for the action to succeed. Nothing reaches the remote: push and + # vcs_release stay off, so the commit and the tag exist only inside this run and the + # branch is left untouched. + commit: 'true' + tag: 'true' + push: 'false' + vcs_release: 'false' + # The changelog is generated, so its entry for this version can be reviewed in the + # run summary below. + changelog: 'true' + # This action runs in its own Docker container, which does not include the `build` + # package, so its build_command would fail with "No module named build". The build + # is done in a later step on the runner instead, where it is installed. + build: 'false' + - name: Show the version that would be released + run: | + echo "::notice::Rehearsal version: ${{ steps.version.outputs.version }} (tag ${{ steps.version.outputs.tag }})" + - name: Build sdist and wheel + run: python -m build + - name: Show the changelog entry that would be generated + run: | + python - <<'PY' >> "$GITHUB_STEP_SUMMARY" + import re + import pathlib + + version = '${{ steps.version.outputs.version }}' + text = pathlib.Path('CHANGELOG.rst').read_text(encoding='utf-8') + match = re.search(rf'(v{re.escape(version)} \(.*?)\n(?=\S*\.\. _changelog-|\Z)', text, re.S) + body = match.group(1).rstrip() if match else "No entry was generated for this version." + print(f"## Changelog entry for `{version}`\n") + print("```rst") + print(body) + print("```") + PY + - name: Check distribution metadata + run: twine check dist/* + - name: Upload distribution + uses: actions/upload-artifact@v7 + with: + name: dist-testpypi + path: dist/ + - name: Publish on TestPyPI + uses: pypa/gh-action-pypi-publish@release/v1 + with: + repository-url: https://test.pypi.org/legacy/ + # A rehearsal may be run several times, and TestPyPI rejects uploads of a file + # that already exists. With this, a repeated run reports success instead of + # failing on the duplicate. + skip-existing: true diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 00000000..062988b6 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,126 @@ +name: release + +on: + push: + branches: + - master + +permissions: + contents: read + +# Only one release at a time, and never cancel one in progress: cancelling while +# semantic-release is pushing its version commit would leave the repository inconsistent. +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: false + +jobs: + release: + name: Version and tag + # A commit message containing [skip release] postpones the release: the workflow is + # skipped, and the commits it carries (including feat: and fix: ones) stay pending, so + # the next release includes them. It only affects this workflow, not CI. + if: ${{ !contains(github.event.head_commit.message, '[skip release]') }} + runs-on: ubuntu-latest + permissions: + contents: write # required to push the version commit and the tag + outputs: + released: ${{ steps.release.outputs.released }} + tag: ${{ steps.release.outputs.tag }} + version: ${{ steps.release.outputs.version }} + steps: + - name: Generate GitHub App token + id: ci-token + uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3 + with: + client-id: ${{ vars.GH_CI_APP_CLIENT_ID }} + private-key: ${{ secrets.GH_CI_APP_PRIVATE_KEY }} + permission-contents: write + - name: Checkout master + uses: actions/checkout@v6 + with: + ref: ${{ github.ref_name }} # always the tip of master, not the triggering SHA + fetch-depth: 0 # semantic-release needs the full history and tags + token: ${{ steps.ci-token.outputs.token }} + - name: Force the branch to the current commit + run: git reset --hard "$GITHUB_SHA" + - name: Set up python + uses: actions/setup-python@v6 + with: + python-version: '3.11' + - name: Install build dependencies + run: | + python -m pip install --upgrade pip + pip install build twine + - name: Calculate version, update changelog, commit and tag + id: release + uses: python-semantic-release/python-semantic-release@v10 + with: + github_token: ${{ steps.ci-token.outputs.token }} + # This action runs in its own Docker container, which does not include the `build` + # package, so its build_command would fail with "No module named build". The build + # is done in a later step on the runner instead, where it is installed. + build: 'false' + - name: Build sdist and wheel + if: steps.release.outputs.released == 'true' + run: python -m build + - name: Check distribution metadata + if: steps.release.outputs.released == 'true' + run: twine check dist/* + - name: Upload distribution + if: steps.release.outputs.released == 'true' + uses: actions/upload-artifact@v7 + with: + name: dist + path: dist/ + + publish: + name: Publish on PyPI + needs: release + if: needs.release.outputs.released == 'true' + runs-on: ubuntu-latest + environment: + name: pypi + url: https://pypi.org/p/toolium + permissions: + id-token: write # required for PyPI trusted publishing (OIDC) + steps: + - name: Download distribution + uses: actions/download-artifact@v5 + with: + name: dist + path: dist/ + - name: Publish distribution on PyPI + uses: pypa/gh-action-pypi-publish@release/v1 + + github-release: + name: Publish GitHub release + needs: release + if: needs.release.outputs.released == 'true' + runs-on: ubuntu-latest + permissions: + contents: read # the release is created with the app token, not with this one + steps: + - name: Generate GitHub App token + id: ci-token + uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3 + with: + client-id: ${{ vars.GH_CI_APP_CLIENT_ID }} + private-key: ${{ secrets.GH_CI_APP_PRIVATE_KEY }} + permission-contents: write + - name: Checkout master + uses: actions/checkout@v6 + with: + # publish-action runs `semantic-release publish`, which reads its configuration + # from pyproject.toml, so the repository has to be present in the workspace. + ref: ${{ github.ref_name }} + - name: Download distribution + uses: actions/download-artifact@v5 + with: + name: dist + path: dist/ + - name: Upload the distribution to the GitHub release + uses: python-semantic-release/publish-action@v10 + with: + github_token: ${{ steps.ci-token.outputs.token }} + tag: ${{ needs.release.outputs.tag }} diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 65b6685e..bd683ba3 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,52 +1,52 @@ +================= Toolium Changelog ================= -v3.9.0 ------- +.. + version list -*Release date: In development* +* Add support for Python 3.14 (`#483`_, `bf0eadb`_) -- Add support for Python 3.14 -- Remove Python 3.10 support (Python 3.10 reaches end of life in October 2026) -- Fix scenario status in Allure report when an action before the feature fails: scenarios are now reported as failed instead of skipped. +.. _#483: https://github.com/Telefonica/toolium/pull/483 +.. _bf0eadb: https://github.com/Telefonica/toolium/commit/bf0eadb78a17b1f35ceab4cfa63b0a29b4b8d742 -v3.8.4 ------- +.. _changelog-v3.8.4: -*Release date: 2026-10-19* +v3.8.4 (2026-10-19) +=================== - Add support for reading files with UTF-8 encoding using the `[FILE_UTF8:xxxx]` replacement. - Fix package metadata in `pyproject.toml` to use SPDX license syntax, remove the deprecated license classifier and include `toolium.resources` in the package configuration. -v3.8.3 ------- +.. _changelog-v3.8.3: -*Release date: 2026-07-15* +v3.8.3 (2026-07-15) +=================== - Fix `openai_request` to rename `azure_api_key` and `openai_api_key` parameters to `api_key` to avoid errors when Azure and OpenAI are created. - Add `openai_temperature` and `azure_temperature` parameters to be configurable in `toolium.cfg` file to set the temperature for OpenAI and Azure requests. - Generalize documentation for `openai_request` configuration. -v3.8.2 ------- +.. _changelog-v3.8.2: -*Release date: 2026-07-13* +v3.8.2 (2026-07-13) +=================== - Update the `openai_request` method to centralize logic and allow loading the configuration from `toolium.cfg` file. -v3.8.1 ------- +.. _changelog-v3.8.1: -*Release date: 2026-04-15* +v3.8.1 (2026-04-15) +=================== - Add token usage tracking to OpenAI requests - Add pytest and unittest runners documentation in `Docs `_ - Fix key error when a scenario with accuracy tag is skipped -v3.8.0 ------- +.. _changelog-v3.8.0: -*Release date: 2026-03-13* +v3.8.0 (2026-03-13) +=================== - Add pyproject.toml file for packaging and publishing Toolium - Configure ruff for linting and formatting files, replacing flake8 and black @@ -56,20 +56,20 @@ v3.8.0 - Add llm-as-a-judge methods to use an LLM to evaluate the answer of another LLM and give a similarity score based on the user's question and a reference answer -v3.7.0 ------- +.. _changelog-v3.7.0: -*Release date: 2025-12-02* +v3.7.0 (2025-12-02) +=================== - Fix accuracy tag to exclude skipped executions from total executions count - Add `after_accuracy_scenario` hook to allow custom behavior after accuracy scenario execution - Add csv report for accuracy scenario results - Add text readability assessment function based on the AI libraries that come with the `ai` extra dependency -v3.6.0 ------- +.. _changelog-v3.6.0: -*Release date: 2025-11-20* +v3.6.0 (2025-11-20) +=================== - Remove Python 3.9 support (Python 3.9 reached the end of its life on October 31st, 2025) - Remove xcuitest deprecated `get_window_size` method and replaced it with `get_window_rect` in all mobile actions @@ -85,10 +85,10 @@ v3.6.0 - Add accuracy data tags to behave scenarios using `@accuracy_data_`, e.g. `@accuracy_data_greetings` for accuracy data with greetings suffix, that allows to execute accuracy scenarios with different data sets -v3.5.0 ------- +.. _changelog-v3.5.0: -*Release date: 2025-07-29* +v3.5.0 (2025-07-29) +=================== - Add support for Python 3.13 - Remove Python 3.8 support (Python 3.8 reached the end of its life on October 14th, 2024) @@ -100,27 +100,27 @@ v3.5.0 $ pip install toolium[playwright] -v3.4.0 ------- +.. _changelog-v3.4.0: -*Release date: 2025-03-06* +v3.4.0 (2025-03-06) +=================== - Now Playwright is available to run web tests instead of Selenium by configuring `web_library: playwright` in [Driver] section - Allow setting the number of decimal places for seconds when using the `[NOW]` replacement with a specific format -v3.3.1 ------- +.. _changelog-v3.3.1: -*Release date: 2025-02-05* +v3.3.1 (2025-02-05) +=================== - Allow to save the diff image in jpg format for visual tests working with jpg - Fix the use of the # character in the actions defined in the feature description (Actions Before/After...) -v3.3.0 ------- +.. _changelog-v3.3.0: -*Release date: 2024-11-26* +v3.3.0 (2024-11-26) +=================== - Allow negative indexes for list elements in context searches. Example: [CONTEXT:element.-1] - Add support for JSON strings to the `DICT` and `LIST`` replacement. Example: [DICT:{"key": true}], [LIST:[null]] @@ -131,53 +131,53 @@ v3.3.0 - Update Appium-Python-Client requirement to enable 3 and 4 versions - Deprecate set_text method in InputText class to make it compatible with Appium-Python-Client 3 and 4 -v3.2.0 ------- +.. _changelog-v3.2.0: -*Release date: 2024-09-13* +v3.2.0 (2024-09-13) +=================== - Add `run_storage` dictionary to context to store information during the whole test execution - Update current ChainMap context storages (context.storage, context.feature_storage and context.run_storage) - Allow to store values from steps into desire storage by using [key], [FEATURE:key] and [RUN:key] -v3.1.5 ------- +.. _changelog-v3.1.5: -*Release date: 2024-07-15* +v3.1.5 (2024-07-15) +=================== - Fix `export_poeditor_project` method allowing empty export response - Add `key=value` expressions for selecting elements in the context storage - Upgrade Faker version to 25.9.* - Fix result for action before the feature with error and background to fail scenarios -v3.1.4 ------- +.. _changelog-v3.1.4: -*Release date: 2024-03-25* +v3.1.4 (2024-03-25) +=================== - Add `ignore_empty` optional parameter to POEditor configuration to ignore empty translations - Ignore not found excluded elements in visual tests - Fix duration calling to Appium `swipe` method - Fix `[STRING_WITH_LENGTH_NN]` replacement for string with length inside a longer string -v3.1.3 ------- +.. _changelog-v3.1.3: -*Release date: 2024-02-06* +v3.1.3 (2024-02-06) +=================== - Fix `PageElements` class initialization when custom page element classes don't have all optional attributes -v3.1.2 ------- +.. _changelog-v3.1.2: -*Release date: 2024-02-05* +v3.1.2 (2024-02-05) +=================== - Upgrade Pillow version to 10.1.* to fix compatibility with Python 3.12 -v3.1.1 ------- +.. _changelog-v3.1.1: -*Release date: 2024-02-02* +v3.1.1 (2024-02-02) +=================== - Add support for Python 3.12 - Upgrade Sphinx version from 4.* to 7.* to fix readthedocs theme format @@ -185,10 +185,10 @@ v3.1.1 - Do not log warning messages when toolium system properties are used - Allow to initialize a `PageElements` class with webview attributes -v3.1.0 ------- +.. _changelog-v3.1.0: -*Release date: 2023-09-19* +v3.1.0 (2023-09-19) +=================== - Update `[CONTEXT:a.b.c]` replacement to allow lists access, e.g. [CONTEXT:list.1] to access the second element of list - Add capabilities configured in `[Capabilities]` section also to Appium tests to use `platformName` and `browserName` @@ -198,20 +198,20 @@ v3.1.0 - Remove Python 3.7 support (Python 3.7 reached the end of its life on June 27th, 2023) - Update _android_automatic_context_selection method to be compatible with latest chromedriver versions -v3.0.2 ------- +.. _changelog-v3.0.2: -*Release date: 2023-06-08* +v3.0.2 (2023-06-08) +=================== - `context.storage` must be initialized before dynamic environment steps in `before_feature` method - Mark scenario as failed when a dynamic environment step fails in `before_scenario` - Mark all feature scenarios as failed when a dynamic environment step fails in `before_feature` and `after_feature` - Configure minimal Appium-Python-Client version to 2.3.0 to avoid import errors -v3.0.1 ------- +.. _changelog-v3.0.1: -*Release date: 2023-05-09* +v3.0.1 (2023-05-09) +=================== - Allow to search in `context.storage` using `[CONTEXT:a.b.c]` replacement when `before_feature` method is not used - Execute after scenario methods also when a scenario is skipped to assure that scenario preconditions are cleaned @@ -219,10 +219,10 @@ v3.0.1 - `context.storage` must be initialized before dynamic environment steps in `before_scenario` method - Fix error in Python 3.11 executing nose2 tests -v3.0.0 ------- +.. _changelog-v3.0.0: -*Release date: 2023-05-03* +v3.0.0 (2023-05-03) +=================== - Add support for Python 3.11 - Add support for Selenium 4 @@ -248,64 +248,64 @@ v3.0.0 - Update `[CONTEXT:a.b.c]` replacement to search data in context, context.storage and context.feature_storage - Update `[CONTEXT:a.b.c]` replacement to allow dictionaries or classes in context fields -v2.7.0 ------- +.. _changelog-v2.7.0: -*Release date: 2023-02-24* +v2.7.0 (2023-02-24) +=================== - Fix drivers not being closed in `after_feature` when errors occur during `before_feature` steps execution - Allow to add extensions to chrome options from properties file New config section [ChromeExtensions] with extensions file paths, e.g. 'firebug: resources/firebug-lite.crx' -v2.6.3 ------- +.. _changelog-v2.6.3: -*Release date: 2022-12-09* +v2.6.3 (2022-12-09) +=================== - Fix error in Android automatic context selection when context does not contain pages - Remove Python 3.6 support (Python 3.6 reached the end of its life on December 23th, 2021) -v2.6.2 ------- +.. _changelog-v2.6.2: -*Release date: 2022-10-18* +v2.6.2 (2022-10-18) +=================== - New param [UUID] in *replace_param* method to generate a v4 UUID - Improve POEditor error message when there are more than one project -v2.6.1 ------- +.. _changelog-v2.6.1: -*Release date: 2022-06-28* +v2.6.1 (2022-06-28) +=================== - Reference dotted keys when saving objects in context storage using [CONTEXT:a.b.c] formula - Fix Visual testing image size for MacOS Retina and mobile layout -v2.6.0 ------- +.. _changelog-v2.6.0: -*Release date: 2022-04-29* +v2.6.0 (2022-04-29) +=================== - Update map_param method to allow recursive replacements - Update replace_param function to allow multiple date expressions in the same param - Fix error message to show parent locator instead of object reference when an element is not found - Update replace_param function to allow NOW datetime expressions with arbitrary formats accepted by datetime.strftime -v2.5.0 ------- +.. _changelog-v2.5.0: -*Release date: 2022-03-16* +v2.5.0 (2022-03-16) +=================== - Update map_param method to use dataset global variables instead of context parameter - Dataset variables needed for TOOLIUM, CONTEXT and POE replacements are set automatically - Make POEditor methods independent of behave context - Fix POEditor bug writing to file when terms contain slashes: from 'http:\/\/www.example.com' to 'http://www.example.com' -v2.4.0 ------- +.. _changelog-v2.4.0: -*Release date: 2022-03-04* +v2.4.0 (2022-03-04) +=================== - Add set_file_path and set_base64_path functions to dataset module, to set base paths for FILE and BASE64 mappings - Visual testing baseline images are copied to output folder to facilitate report visualization in Jenkins @@ -313,19 +313,19 @@ v2.4.0 - Fix detection of POEditor configuration not available - Fix indent error in Driver Configuration documentation -v2.3.0 ------- +.. _changelog-v2.3.0: -*Release date: 2022-02-03* +v2.3.0 (2022-02-03) +=================== - Add missing param in download_videos method to fix error downloading videos from a remote server - Add map_param function to dataset module - New param [RANDOM_PHONE_NUMBER] in *replace_param* method to generate random phone number -v2.2.1 ------- +.. _changelog-v2.2.1: -*Release date: 2022-01-11* +v2.2.1 (2022-01-11) +=================== - Add support for Python 3.10 - Add support for Appium-Python-Client 1.3.0 @@ -333,10 +333,10 @@ v2.2.1 - Move code quality check from codacy to codeclimate - Upgrade Sphinx version from 3.* to 4.* to fix doc compilation errors in readthedocs -v2.2.0 ------- +.. _changelog-v2.2.0: -*Release date: 2021-11-03* +v2.2.0 (2021-11-03) +=================== - Add JSON object/list conversion to Python dict/list in the type inference logic of the *replace_param* function - Add *finalize_properties_configuration* method in *DriverWrapper* class to allow the modification of config properties @@ -361,29 +361,29 @@ v2.2.0 $ behave -D TOOLIUM_CONFIG_ENVIRONMENT=android -v2.1.1 ------- +.. _changelog-v2.1.1: -*Release date: 2021-09-22* +v2.1.1 (2021-09-22) +=================== - Avoid to overwrite parent in group elements when a custom parent is defined - Fix Chrome options to allow to configure them at the same time in *Chrome* sections and in *goog:chromeOptions* capability -v2.1.0 ------- +.. _changelog-v2.1.0: -*Release date: 2021-07-05* +v2.1.0 (2021-07-05) +=================== - Add type inference and improve replacement logic in *replace_param* function - Remove *generate_fixed_length_param* function, as all possible transformations are available in *replace_param* - Fix docutils development dependency to version 0.16 - Fix InputText element class getting the text value for mobile apps in webview mode -v2.0.0 ------- +.. _changelog-v2.0.0: -*Release date: 2021-06-15* +v2.0.0 (2021-06-15) +=================== - Remove Python 2.7, 3.3 and 3.4 support - Update deprecated methods to fix warnings in python3 execution @@ -392,27 +392,27 @@ v2.0.0 - Fix report when an error happens in the Dynamic Environment - New param [TIMESTAMP] in *replace_param* method to generate timestamp value of the actual moment -v1.9.2 ------- +.. _changelog-v1.9.2: -*Release date: 2021-04-09* +v1.9.2 (2021-04-09) +=================== - Fix error in *deepcopy* method of *ExtendedConfigParser* class when two config properties have colon in name -v1.9.1 ------- +.. _changelog-v1.9.1: -*Release date: 2021-03-11* +v1.9.1 (2021-03-11) +=================== - Added new method wait_until_ajax_request_completed to driver utils class - Move CI from Travis to Github Actions - Fix string conversion in dataset utilities - Add upper/lower conversion to replace param method -v1.9.0 ------- +.. _changelog-v1.9.0: -*Release date: 2021-03-02* +v1.9.0 (2021-03-02) +=================== - Added utilities to download files - Get text for InputText element in mobile tests @@ -420,30 +420,30 @@ v1.9.0 - Add dataset utilities - Manage multiples webviews for mobile tests -v1.8.2 ------- +.. _changelog-v1.8.2: -*Release date: 2020-12-17* +v1.8.2 (2020-12-17) +=================== - Add support for python 3.9 - Add *get_driver_name* method to driver utils class - Add doc about how to configure Firefox device mode - Fix driver log types documentation -v1.8.1 ------- +.. _changelog-v1.8.1: -*Release date: 2020-11-02* +v1.8.1 (2020-11-02) +=================== - Create logs folder before downloading driver logs - Add *set_focus* method to common elements and input text elements - Fix driver log types list in local executions - Fix automatic_context_selection for group element -v1.8.0 ------- +.. _changelog-v1.8.0: -*Release date: 2020-10-05* +v1.8.0 (2020-10-05) +=================== - Allow lists in config properties instead of converting them to strings - Fix typo in documentation for configuration Server log types @@ -453,26 +453,26 @@ v1.8.0 | If it's false, the WebElement is searched using always NATIVE context | If it's true, the WebElement is searched using context NATIVE or WEBVIEW depeding of the webview attribute value -v1.7.2 ------- +.. _changelog-v1.7.2: -*Release date: 2020-09-01* +v1.7.2 (2020-09-01) +=================== - Move utils.py and path_utils.py files to utils folder maintaining backwards compatibility - Fix input text when element has a shadowroot and text contains quotation marks - New config property 'log_types' in [Server] section to configure webdriver log types that should be downloaded -v1.7.1 ------- +.. _changelog-v1.7.1: -*Release date: 2020-05-18* +v1.7.1 (2020-05-18) +=================== - Fix Appium dependency conflict, current allowed versions: from 0.24 to 0.52 -v1.7.0 ------- +.. _changelog-v1.7.0: -*Release date: 2020-05-11* +v1.7.0 (2020-05-11) +=================== - Fix to allow step's text (context.text) declaration into dynamic environment sections - Add `ssl` config property in [Server] section to allow using https in Selenium Grid url @@ -481,17 +481,17 @@ v1.7.0 even when before scenario/feature actions fail - Fix unit tests to work without any additional dependencies -v1.6.1 ------- +.. _changelog-v1.6.1: -*Release date: 2020-01-21* +v1.6.1 (2020-01-21) +=================== - Fix concurrent folder creation. Add *makedirs_safe* method to create a new folder. -v1.6.0 ------- +.. _changelog-v1.6.0: -*Release date: 2020-01-15* +v1.6.0 (2020-01-15) +=================== - New config property 'binary' in [Chrome] section to configure the chrome binary path - Allow configuration properties with colon in name @@ -511,24 +511,24 @@ v1.6.0 - Add support for python 3.8 -v1.5.6 ------- +.. _changelog-v1.5.6: -*Release date: 2019-10-04* +v1.5.6 (2019-10-04) +=================== - Fix dynamic environment exit code when there are hook errors -v1.5.5 ------- +.. _changelog-v1.5.5: -*Release date: 2019-07-29* +v1.5.5 (2019-07-29) +=================== - Fix screeninfo dependency to 0.3.1 version -v1.5.4 ------- +.. _changelog-v1.5.4: -*Release date: 2019-07-22* +v1.5.4 (2019-07-22) +=================== - Add support to encapsulated elements (Shadowroot) @@ -540,36 +540,36 @@ v1.5.4 - Fix Selenium dependency conflict -v1.5.3 ------- +.. _changelog-v1.5.3: -*Release date: 2019-04-05* +v1.5.3 (2019-04-05) +=================== - Fix error executing Appium locally -v1.5.2 ------- +.. _changelog-v1.5.2: -*Release date: 2019-04-01* +v1.5.2 (2019-04-01) +=================== - Check if a GGR session (current) is still active - Download Selenoid logs files also when test fails - Fix utils.py wait functions' descriptions - Add new wait to utils.py in order to wait for an element not containing some text -v1.5.1 ------- +.. _changelog-v1.5.1: -*Release date: 2019-03-18* +v1.5.1 (2019-03-18) +=================== - Download Selenoid video and logs files only in linux nodes if video or logs are enabled - Add a sleep between Selenoid retries when downloading files - Manage exceptions in dynamic environment to mark affected scenarios as failed -v1.5.0 ------- +.. _changelog-v1.5.0: -*Release date: 2019-02-26* +v1.5.0 (2019-02-26) +=================== - Latest version of Appium can be used - Make Toolium compatible with GGR and Selenoid @@ -577,17 +577,17 @@ v1.5.0 - Add logs path in the `_output` folder to download GGR logs - Add `username` and `password` config properties in [Server] section to enable basic authentication in Selenium Grid (required by GGR) -v1.4.3 ------- +.. _changelog-v1.4.3: -*Release date: 2018-12-18* +v1.4.3 (2018-12-18) +=================== - Fix Appium version to 0.31 or minor -v1.4.2 ------- +.. _changelog-v1.4.2: -*Release date: 2018-10-26* +v1.4.2 (2018-10-26) +=================== - Add movement in X axis in *scroll_element_into_view* method - Fix bugs and new features in the Dynamic Environment library: @@ -600,10 +600,10 @@ v1.4.2 - Add support for python 3.7 -v1.4.1 ------- +.. _changelog-v1.4.1: -*Release date: 2018-02-26* +v1.4.1 (2018-02-26) +=================== - Fix README.rst format to be compatible with pypi - Fix `after_scenario` error when toolium `before_feature` is not used @@ -613,10 +613,10 @@ v1.4.1 - New config properties 'monitor', 'bounds_x' and 'bounds_y' in [Driver] section to configure browser bounds and monitor - Normalize filenames to avoid errors with invalid characters -v1.4.0 ------- +.. _changelog-v1.4.0: -*Release date: 2018-02-04* +v1.4.0 (2018-02-04) +=================== - Add pytest fixtures to start and stop drivers - New config property `reuse_driver_session` in [Driver] section to use the same driver in all tests @@ -626,10 +626,10 @@ v1.4.0 - Fix output log name when `Config_environment` is used - Fix Chrome options using remote drivers with Selenium >= 3.6.0 -v1.3.0 ------- +.. _changelog-v1.3.0: -*Release date: 2017-09-12* +v1.3.0 (2017-09-12) +=================== - Add Behave dynamic environment (more info in `Docs `_) - Fix visual screenshot filename error when behave feature name contains : @@ -640,51 +640,51 @@ v1.3.0 - Add @reset_driver scenario tag to restart driver before a behave scenario, even if reuse_driver is true - Add *is_present* and *is_visible* methods to PageElement classes to know if an element is present or visible -v1.2.5 ------- +.. _changelog-v1.2.5: -*Release date: 2017-03-24* +v1.2.5 (2017-03-24) +=================== - Fix firefox initialization error using Selenium 2.X - Add *wait_until_loaded* method to PageObject class to wait until all page elements with wait=True are visible -v1.2.4 ------- +.. _changelog-v1.2.4: -*Release date: 2017-03-17* +v1.2.4 (2017-03-17) +=================== - Fix NoSuchElementException error finding elements in nested groups -v1.2.3 ------- +.. _changelog-v1.2.3: -*Release date: 2017-03-10* +v1.2.3 (2017-03-10) +=================== - Save *geckodriver.log* file in output folder - Fix MagickEngine name error when using an old version of needle - Add *wait_until_clickable* method to Utils and PageElement classes to search for an element and wait until it is clickable -v1.2.2 ------- +.. _changelog-v1.2.2: -*Release date: 2017-02-01* +v1.2.2 (2017-02-01) +=================== - Fix error comparing screenshots in mobile tests - Fix image size when enlarging a vertical image in visual testing reports - Move js and css out of visual html report to avoid CSP errors -v1.2.1 ------- +.. _changelog-v1.2.1: -*Release date: 2017-01-18* +v1.2.1 (2017-01-18) +=================== - Fix error installing Toolium when setuptools version is too old -v1.2.0 ------- +.. _changelog-v1.2.0: -*Release date: 2017-01-17* +v1.2.0 (2017-01-17) +=================== - Refactored reset_object method. Now it has an optional parameter with the driver_wrapper. - Fix error reading geckodriver logs after test failure @@ -711,10 +711,10 @@ v1.2.0 $ behave -D Config_environment=android -v1.1.3 ------- +.. _changelog-v1.1.3: -*Release date: 2016-11-18* +v1.1.3 (2016-11-18) +=================== - Video download works in Selenium Grid 3 - New config property 'binary' in [Firefox] section to configure the firefox binary path @@ -723,25 +723,25 @@ v1.1.3 - Fix wait_until_element_visible and wait_until_element_not_visible methods when the page element has a parent element - Add *imagemagick* as visual engine to have better diff images -v1.1.2 ------- +.. _changelog-v1.1.2: -*Release date: 2016-07-19* +v1.1.2 (2016-07-19) +=================== - Baseline name property can contain *{Version}* to add actual version capability value to the baseline name - New config property 'gecko_driver_path' in [Browser] section to configure the Gecko/Marionette driver location -v1.1.1 ------- +.. _changelog-v1.1.1: -*Release date: 2016-06-30* +v1.1.1 (2016-06-30) +=================== - Save webdriver logs of each driver, not just the first one, and only if test fails -v1.1.0 ------- +.. _changelog-v1.1.0: -*Release date: 2016-06-03* +v1.1.0 (2016-06-03) +=================== - New MobilePageObject class to test Android and iOS apps with the same base page objects - Fix visual report links in Windows @@ -753,19 +753,19 @@ v1.1.0 $ behave -D env=android -v1.0.1 ------- +.. _changelog-v1.0.1: -*Release date: 2016-05-09* +v1.0.1 (2016-05-09) +=================== - Fix wait_until_first_element_is_found error when element is None - Fix app_strings initialization in page objects - Fix swipe method to work with Appium 1.5 swipe -v1.0.0 ------- +.. _changelog-v1.0.0: -*Release date: 2016-04-12* +v1.0.0 (2016-04-12) +=================== DRIVER @@ -813,20 +813,19 @@ VISUAL TESTING - Baseline name property can contain *{PlatformVersion}* or *{RemoteNode}* to add actual platform version or remote node name to the baseline name +.. _changelog-v0.12.1: -v0.12.1 -------- - -*Release date: 2016-01-07* +v0.12.1 (2016-01-07) +==================== - Fix app_strings initialization in Behave Appium tests - In Behave tests, Toolium config is saved in context.toolium_config instead of using context.config to avoid overriding Behave config -v0.12.0 -------- +.. _changelog-v0.12.0: -*Release date: 2015-12-23* +v0.12.0 (2015-12-23) +==================== - Allow to create a second driver using DriverWrapper constructor: @@ -841,10 +840,10 @@ v0.12.0 - Move set_config_* and set_output_* test case methods to ConfigFiles class - Add behave environment file to initialize Toolium wrapper from behave tests -v0.11.3 -------- +.. _changelog-v0.11.3: -*Release date: 2015-11-24* +v0.11.3 (2015-11-24) +==================== - Fix image size in visual testing for Android and iOS web tests - Baseline name property allows any configuration property value to configure the visual testing baseline folder, e.g.: @@ -854,17 +853,17 @@ v0.11.3 - Fix page elements initialization when they are defined outside of a page object -v0.11.2 -------- +.. _changelog-v0.11.2: -*Release date: 2015-11-11* +v0.11.2 (2015-11-11) +==================== - Compatibility with Python 3 -v0.11.1 -------- +.. _changelog-v0.11.1: -*Release date: 2015-11-02* +v0.11.1 (2015-11-02) +==================== - New config property 'operadriver_path' in [Browser] section to configure the Opera Driver location - Fix initialization error when a page object contains another page object @@ -873,18 +872,18 @@ v0.11.1 - Configure setup.py to execute tests with 'python setup.py test' - Convert markdown (.md) files to reStructuredText (.rst) and update long_description with README.rst content -v0.11.0 -------- +.. _changelog-v0.11.0: -*Release date: 2015-10-21* +v0.11.0 (2015-10-21) +==================== - Rename library from seleniumtid to toolium - Distributed under Apache Software License, Version 2 -v0.10.0 -------- +.. _changelog-v0.10.0: -*Release date: 2015-09-23* +v0.10.0 (2015-09-23) +==================== - Add support to Edge Windows browser - New config property 'summary_prefix' in [Jira] section to modify default TCE summary @@ -905,10 +904,10 @@ v0.10.0 - Add set_config_* and set_output_* test case methods to configure output and config files instead of using configuration system properties -v0.9.3 ------- +.. _changelog-v0.9.3: -*Release date: 2015-07-24* +v0.9.3 (2015-07-24) +=================== - Allow to set custom driver capabilities from properties file @@ -917,28 +916,28 @@ v0.9.3 - Fix set_value and app_strings errors in mobile web tests - Fix set_value error in iOS tests when using needle -v0.9.2 ------- +.. _changelog-v0.9.2: -*Release date: 2015-06-02* +v0.9.2 (2015-06-02) +=================== - Allow to find elements by ios_uiautomation in visual assertions - Fix app_strings error in mobile web tests - Use set_value instead of send_keys to run tests faster -v0.9.1 ------- +.. _changelog-v0.9.1: -*Release date: 2015-05-21* +v0.9.1 (2015-05-21) +=================== - Add swipe method in Utils to allow swipe over an element - Only one property file is mandatory if *Files_properties* has multiple values - Allow to exclude elements from visual screenshots -v0.9.0 ------- +.. _changelog-v0.9.0: -*Release date: 2015-05-12* +v0.9.0 (2015-05-12) +=================== - Output path (screenshots, videos, visualtests) can be specified with a system property: *Files_output_path* - Update app_strings in Appium tests only if the driver has changed @@ -959,60 +958,60 @@ v0.9.0 - Add assertFullScreenshot method in SeleniumTestCase -v0.8.6 ------- +.. _changelog-v0.8.6: -*Release date: 2015-04-17* +v0.8.6 (2015-04-17) +=================== - Add wait_until_element_visible method in utils class - Logger filename can be specified with a system property: *Files_log_filename* -v0.8.5 ------- +.. _changelog-v0.8.5: -*Release date: 2015-03-23* +v0.8.5 (2015-03-23) +=================== - Add Button page element - AppiumTestCase has a new attribute app_strings, a dict with application strings in the active language -v0.8.4 ------- +.. _changelog-v0.8.4: -*Release date: 2015-03-05* +v0.8.4 (2015-03-05) +=================== - Allow to set firefox and chrome preferences from properties file | New config section [FirefoxPreferences] with firefox preferences, e.g. 'browser.download.dir = /tmp' | New config section [ChromePreferences] with chrome preferences, e.g. 'download.default_directory = /tmp' -v0.8.3 ------- +.. _changelog-v0.8.3: -*Release date: 2015-02-11* +v0.8.3 (2015-02-11) +=================== - Read properties file before each test to allow executing tests with different configurations (android, iphone, ...) -v0.8.2 ------- +.. _changelog-v0.8.2: -*Release date: 2015-02-04* +v0.8.2 (2015-02-04) +=================== - Logging and properties config files can be specified with a system property: *Files_logging* and *Files_properties* *Files_properties* allows multiple files separated by ; -v0.8.1 ------- +.. _changelog-v0.8.1: -*Release date: 2015-01-26* +v0.8.1 (2015-01-26) +=================== - Fixed minor bugs - Add visual testing to lettuce tests -v0.8 ----- +.. _changelog-v0.8: -*Release date: 2015-01-20* +v0.8 (2015-01-20) +================= - Add visual testing to SeleniumTestCase and AppiumTestCase @@ -1020,59 +1019,59 @@ v0.8 | New config property 'visualtests_save' in [Server] section to overwrite baseline images with actual screenshots | New config property 'visualtests_engine' in [Server] section to select image engine (pil or perceptualdiff) -v0.7 ----- +.. _changelog-v0.7: -*Release date: 2014-12-23* +v0.7 (2014-12-23) +================= - Allow to autocomplete self.driver and self.utils in IDEs - Remove non-mandatory requirements -v0.6 ----- +.. _changelog-v0.6: -*Release date: 2014-12-05* +v0.6 (2014-12-05) +================= - Multiple tests of a class can be linked to the same Jira Test Case - If test fails, the error message will be added as a comment to the Jira Test Case Execution - Update Jira Test Cases also in lettuce tests -v0.5 ----- +.. _changelog-v0.5: -*Release date: 2014-12-01* +v0.5 (2014-12-01) +================= - Downloads the saved video if the test has been executed in a VideoGrid - Add BasicTestCase class to be used in Api tests or in other tests without selenium driver -v0.4 ----- +.. _changelog-v0.4: -*Release date: 2014-11-12* +v0.4 (2014-11-12) +================= - Add Lettuce terrain file to initialize Selenium driver - Add ConfigDriver.create_driver method to create a new driver with specific configuration - Add wait_until_element_not_visible method in utils class -v0.3 ----- +.. _changelog-v0.3: -*Release date: 2014-06-12* +v0.3 (2014-06-12) +================= - Add a config property 'implicitly_wait' in [Common] section to set an implicit timeout - Add a config property 'reuse_driver' in [Common] section to use the same driver in all tests of each class - The driver can be reused only in a test class setting a class variable 'reuse_driver = True' -v0.2 ----- +.. _changelog-v0.2: -*Release date: 2014-05-13* +v0.2 (2014-05-13) +================= - Now depends on Appium 1.0 -v0.1 ----- +.. _changelog-v0.1: -*Release date: 2014-03-04* +v0.1 (2014-03-04) +================= - First version of the selenium library in python diff --git a/README.rst b/README.rst index 871d5ea8..70b8b875 100644 --- a/README.rst +++ b/README.rst @@ -95,6 +95,9 @@ Finally, before accepting your contribution, we need you to sign our `Contributor License Agreement `_ and send it to ruben.gonzalezalonso@telefonica.com. +If you are a maintainer, see `RELEASING.md `_ +for the steps to publish a new release. + Main Features ------------- diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 00000000..77ce9d25 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,158 @@ +# Releasing Toolium + +Releases are fully automated. Every merge to `master` is analysed by +[python-semantic-release](https://python-semantic-release.readthedocs.io/) (PSR), which decides the next version, +updates the version and the changelog, commits, tags, and publishes. **There is no manual release step.** + +## Versioning rules + +The next version is derived from the commit messages, following +[Conventional Commits](https://www.conventionalcommits.org/). Three prefixes are recognised — `feat:`, `fix:` and +`chore:` — with these effects: + +| Commit prefix | Effect | +| --- | --- | +| `feat:` | Minor release (`3.9.0` → `3.10.0`) | +| `fix:` | Patch release (`3.9.0` → `3.9.1`) | +| `feat!:` or a `BREAKING CHANGE:` footer | Major release (`3.9.0` → `4.0.0`) | +| `chore:` | No release on its own; it appears in the changelog when something else releases | +| anything else (`docs:`, `ci:`, `test:`, `perf:`, `refactor:`, `style:`, `build:`, …) | **Ignored**: no version bump and no changelog entry | + +The prefix list is set in `pyproject.toml` (`minor_tags`, `patch_tags`, `other_allowed_tags` and `allowed_tags`) and is +deliberately narrow. A change worth publishing must use one of the three prefixes above; otherwise it is silently +dropped, both from the version and from the changelog. In particular, a performance improvement is written as `fix:`, +not `perf:`, so that it reaches the patch release and the changelog. + +Commits that do not follow the convention are ignored for versioning. A merge that releases nothing simply skips the +whole workflow. + +**The pull request title is the commit message.** Pull requests are merged with squash, so the title of the PR becomes +the single commit that lands on `master` — and that is what semantic-release reads. A malformed title is silently +ignored: it will not bump the version and will not appear in the changelog. Note that a prefix with a missing colon is +not recognised: `feat(scope) text` is ignored, `feat(scope): text` is not. Editing the PR title after it has been +merged does **not** fix it, because the commit message is already written and cannot be changed. + +**Only the title is read**, not the list of commits that GitHub writes below it (`parse_squash_commits = false` in +`pyproject.toml`). That list holds the individual commits of the branch, which are often written without this +convention in mind, and it would let a change slip into the version and the changelog unnoticed. The title, on the +other hand, is reviewed before merging and can be corrected at any point while the PR is open, so it is the only thing +that decides the release. A consequence worth knowing: a `feat!:` buried in the branch whose PR is titled `chore:` will +not raise the major version. + +Because the version is derived from the commits, `VERSION` is never edited by hand again, and the `X.Y.Z.dev0` scheme +is no longer used: after a release, `VERSION` holds the released version, and the next release is computed from it. + +### Postponing a release + +To land a change without releasing it, put `[skip release]` in the **pull request title**. The release workflow is +skipped, but the commits it carries stay pending, so the **next** release includes them — with their own entry in the +changelog and their own effect on the version. It only affects the release workflow, not CI, which runs as usual. + +``` +feat!: remove the deprecated page object API [skip release] +``` + +The PR title is where the marker has to go because that is what a squash merge copies into the commit that lands on +`master`. The body of the commit is not reliable: it survives in a single-commit pull request but is dropped when the +pull request has more than one commit, so a marker there would be lost and the release would go out. + +This is useful to group related changes into a single release: merge the first PR with the marker, and merge the last +one without it. Both `feat:` entries then appear together in the same release. + +Note that the marker ends up in the changelog entry of the release it lands in, since it is part of the title that +generates it (`* Remove the deprecated page object API [skip release]`). Remove it by hand from that entry afterwards. + +A `chore:` does not release on its own either, but it does appear in the changelog under its own section, so it is the +one to use for maintenance that should be listed. Use `[skip release]` instead when the change must stay out of the +changelog until it is released together with something else — which is the only option for a `feat:` that should not +trigger a release yet. + +## What happens on a merge to master + +`.github/workflows/release.yml` runs: + +1. Checks out `master` and runs python-semantic-release, which calculates the next version from the commits since the + last tag, rewrites `VERSION`, inserts the new entry in `CHANGELOG.rst`, commits, tags, and builds the distributions. +2. Publishes the distributions on PyPI using Trusted Publishing (OIDC), with PEP 740 attestations enabled. +3. Creates the GitHub release for the tag and attaches the sdist and the wheel. + +If the commits since the last tag do not justify a release, the workflow stops after step 1 and nothing is published. + +Version commits are named `chore(release): X.Y.Z` and are excluded from the changelog. + +### The GitHub App token + +The workflow does not push with the built-in `GITHUB_TOKEN`, but with a token generated from the +**`cross-cutting-devex` GitHub App** (`vars.GH_CI_APP_CLIENT_ID` and `secrets.GH_CI_APP_PRIVATE_KEY`). This is needed +because the version commit and the tag are pushed straight to `master`, which is protected: the app is the identity +allowed to do it, instead of having to exempt the `github-actions` bot from the rule. + +One consequence: a push made with an app token **does** trigger workflows, unlike one made with `GITHUB_TOKEN`. So the +version commit starts a second run of this same workflow, which finds no new `fix:` or `feat:` and does nothing, and +also a run of CI over that commit. That is expected, and it does not loop. + +If the app is renamed or replaced, update the two values above and the workflow, and note that the workflow pushes on +behalf of that app. + +## Verifying a release + +- PyPI: +- GitHub releases: +- Actions runs: +- The attestations of a published file are visible on its PyPI page, under *Provenance*. + +To preview the next version locally, without releasing anything: + +```bash +pip install python-semantic-release +semantic-release version --print +``` + +## Rehearsing the flow + +`.github/workflows/release-test.yml` builds a prerelease and publishes it on +[TestPyPI](https://test.pypi.org/project/toolium/), so the whole flow can be tried without +publishing anything real: + +- It can be started manually from the *Actions* tab, or by pushing to a branch named `test/*`. + The manual button only appears once the file is on `master`; pushing to a `test/*` branch + works before that. +- The version is a prerelease (`X.Y.Z-dev.N`). The release commit and tag are created locally + inside the run to satisfy the action, but nothing is pushed: the remote branches and tags + are left as they were, and PyPI never sees the rehearsal. +- The changelog entry that the release would generate is shown in the run summary, so it can + be reviewed before the real release. +- It needs the `testpypi` environment and a trusted publisher on TestPyPI configured the + same way as the one on PyPI (same repository, workflow `release-test.yml`). + +To install a rehearsed build: + +```bash +pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ toolium==X.Y.Z.devN +``` + +## The changelog + +`CHANGELOG.rst` is no longer edited by hand. When a release happens, semantic-release inserts the section of the new +version right below the document title, and **leaves everything below it untouched**, so the entries written before the +automation are kept exactly as they were. + +For uniformity, the historical entries were reformatted once to the format used by semantic-release: each version is +now a heading like `vX.Y.Z (YYYY-MM-DD)` with the date inside the heading, instead of a `vX.Y.Z` heading followed by a +`*Release date: ...*` line. Only the headings and dates were moved; the text of every entry is unchanged. + +From `v3.9.0` onwards, the entries of each release are generated from its commits: they summarise the commit subjects +and link to the pull request and the commit of each change. Because of this, **a clear conventional commit message is +what produces a good changelog entry**. + +The insertion point is marked by the `..` / `version list` comment block at the top of the file. Do not remove it, or +semantic-release will be unable to insert the notes of the next release. + +If a change was missed because its commit message could not be parsed, add its line by hand to the existing changelog, +right below that marker, before the release. semantic-release keeps it and places it inside the new version's section +when inserting the generated entries. + +`CHANGELOG.rst` must keep LF line endings: semantic-release looks for that marker using the line separator of the +platform, so the file is pinned to LF in `.gitattributes`. An editor that writes CRLF will break the insertion +silently: the release would publish with the changelog left as it was. Check with +`file CHANGELOG.rst`, or look for `^M$` line endings, if a release's entry is ever missing. diff --git a/pyproject.toml b/pyproject.toml index b628f305..e920cf45 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -147,3 +147,54 @@ quote-style = "single" indent-style = "space" skip-magic-trailing-comma = false line-ending = "auto" + +[tool.semantic_release] +assets = [] +commit_parser = "conventional" +tag_format = "{version}" +commit_message = "chore(release): {version}" +version_variables = ["VERSION:*:nf"] +# No build_command on purpose. The semantic-release GitHub action runs inside its own +# Docker container, which does not include the `build` package, so a build_command there +# fails with "No module named build". The distributions are built on the runner instead +# (see the release workflows), and without this setting semantic-release skips the build +# with a clear message. + +[tool.semantic_release.branches.master] +match = "master" + +# Branches used only to rehearse the release flow (see .github/workflows/release-test.yml). +# They produce prerelease versions, so they never collide with a real release. +[tool.semantic_release.branches.test] +match = "test/.*" +prerelease = true +prerelease_token = "dev" + +[tool.semantic_release.changelog] +# Only new releases are appended to the existing changelog, so the entries written +# before the automation are kept as they were. The flag below marks where new release +# notes are inserted; the rest of the file is left untouched. It must match the marker +# in CHANGELOG.rst, which is pinned to LF line endings in .gitattributes because +# semantic-release builds the flag with the line separator of the current platform. +mode = "update" +insertion_flag = "..\n version list" +# Do not list the version bump commits generated by semantic-release itself. +exclude_commit_patterns = ['chore\(release\):.*'] + +[tool.semantic_release.changelog.default_templates] +changelog_file = "CHANGELOG.rst" +output_format = "rst" + +[tool.semantic_release.commit_parser_options] +minor_tags = ["feat"] +patch_tags = ["fix"] +other_allowed_tags = ["chore"] +# This list must be stated explicitly: semantic-release does not recompute it from the +# three lists above, it keeps its own default (feat, fix, perf, build, chore, ci, docs, +# style, refactor, test). Without this line, docs:, ci: and perf: would still be accepted. +allowed_tags = ["feat", "fix", "chore"] +# Only the pull request title is read, not the list of commits below it. Pull requests are +# merged with squash, and that list often holds commits written without the convention in +# mind. The title is what gets reviewed and can be fixed before merging, so it is the only +# thing that should decide the version and the changelog. +parse_squash_commits = false