Feat/auto creation uvlock

[rafaelpadilla]

Summary

This PR introduces a new GitHub Actions workflow for automatically updating uv.lock and makes small changes in the 2 existing workflows.

The expected flow with these 3 Github Actions is:

PR targeting main
        ↓
Update or validate uv.lock in the same branch of the PR
        ↓
Run linting and tests using the exact resulting commit

Once a PR is merged to the main branch:

PR merge into main
        ↓
Run linting and tests 
        ↓
If tests pass, check whether the package version changed
        ↓
Build and publish the new version to PyPI

1. Workflow update-uv-lock.yml

This workflow runs when a pull request targeting main is:

• Opened
• Reopened
• Updated with new commits
• Edited

The workflow checks out the PR source branch and executes uv lock. If uv.lock is created or modified, the workflow:

1. Adds the updated uv.lock.
2. Creates an Update uv.lock commit.
3. Pushes the commit to the same branch used by the PR.
4. Records the SHA of the new commit.
5. Calls tests.yml using that exact SHA.

If uv.lock is already synchronized with pyproject.toml, the workflow:

1. Does not create a commit.
2. Does not push any changes.
3. Records the current SHA of the PR branch.
4. Calls tests.yml using the current SHA.

Therefore, tests.yml is called regardless of whether uv.lock changes, as long as the job completes successfully.

Concurrent runs for the same PR are cancelled, ensuring that only the latest state of the PR is processed.

For PRs originating from forks, the workflow cannot push changes to the fork using GITHUB_TOKEN. If uv.lock needs to be updated, the workflow fails with a message requesting that the contributor generate and commit the lockfile manually. If the lockfile is already synchronized, the tests proceed normally.

2. Workflow tests.yml

For PRs, this workflow is called by update-uv-lock.yml as a reusable workflow. It receives the exact repository and commit SHA that should be tested.

It is also triggered directly on every push to main, including pushes produced when pull requests are merged.

Dependencies are installed with the uv sync --locked --extra dev file in the branch of the PR. The --locked option guarantees that:

• uv.lock must exist.
• uv.lock must be consistent with pyproject.toml.
• The workflow uses the dependency versions recorded in the lockfile.
• The lockfile cannot be updated silently during CI.

The workflow performs:

• Linting with Python 3.12.
• Tests with Python 3.10, 3.11, and 3.12.
• Coverage upload to Coveralls using Python 3.10.

3. Workflow: publish.yml

This workflow is triggered only after the Tests and Coverage workflow completes for main.

The publication job proceeds only when:

• Tests and Coverage completed successfully.
• The workflow was originally triggered by a push to main.

This prevents package publication while linting or tests are still running and prevents publication if any CI job fails.

The workflow checks out the exact commit validated by Tests and Coverage and compares the package version in pyproject.toml with the version from its parent commit.

If the version is unchanged, package publication is skipped.

If the version changed, the workflow builds the source distribution and wheel and publishes the generated package to PyPI.

Result

These workflows ensure that:

• uv.lock remains synchronized with pyproject.toml.
• The lockfile update is included in the same PR.
• If any member forgets to update the uv.lock with the new dependencies, workflow fails and alerts the user to update the uv.lock.
• uv.lock is generated inside Github structure, preventing need to be manually generated by the client's own machine. (Useful for PETROBRAS users) 😃
• PRs are tested using the exact generated or existing lockfile
• The merged code is tested again on main, making sure the main is always being tested even if a force push is performed.
• Package publication only occurs after successful CI.
• A package is published only when its version changes.

---

By creating this pull request, I confirm that I have read and fully accept and agree with one of the Petrobras' Contributor License Agreements (CLAs):

• ICLA: Individual Contributor License Agreement on behalf of only yourself;
• CCLA: Corporate Contributor License Agreement on behalf of your employer.

Our CLAs are based on the Apache Software Foundation's CLAs:

• ICLA: Individual Contributor License Agreement
• CCLA: Corporate Contributor License Agreement

[rafaelpadilla]

For clarity, adding here a diagram detailing the expected behavior:

flowchart TD
    PR["PR targeting main<br/>opened, reopened, updated, or edited"]
    Lock["update-uv-lock.yml<br/>Run uv lock"]
    Changed{"uv.lock changed?"}
    Commit["Commit uv.lock<br/>to the PR branch"]
    Current["Use current PR commit"]
    TestsPR["tests.yml<br/>Lint and test the exact commit"]

    Merge["Merge or push to main"]
    TestsMain["tests.yml<br/>Lint and test main"]
    Passed{"CI passed?"}
    Version{"Package version changed?"}
    Publish["Build and publish to PyPI"]
    Skip["Skip publication"]

    PR --> Lock
    Lock --> Changed
    Changed -->|Yes| Commit
    Changed -->|No| Current
    Commit --> TestsPR
    Current --> TestsPR

    TestsPR --> Merge
    Merge --> TestsMain
    TestsMain --> Passed
    Passed -->|No| Skip
    Passed -->|Yes| Version
    Version -->|No| Skip
    Version -->|Yes| Publish
    ````

[Mathtzt]

Hi @rafaelpadilla

Thank you so much for the contribution and all the effort! 👏🏼

This is an excellent addition to our CI/CD pipeline. The automated lockfile synchronization ensures that pyproject.toml and uv.lock remain fully deterministic without requiring local manual intervention, resolving the issue for PETROBRAS users. With this, we can guarantee that the CI check fails early whenever there is a dependency mismatch.

I also appreciate our conversation about the lockfile, which gave me new insights into the best practices for version locking.