Fix bump.sh release CI step

[paolino]

Why

Last bump.sh release push is reporting a wrong version number. We deployed version v2024-09-03 and v2024-08-11 was found on bump.sh.

The push-to-bump.sh step in the release pipeline checked out the right commit, 3bf4d7d which contains a swagger.yaml on the v2024-09-03 version, but after the push , the deployment shows the old v2024-08-11 version.

https://bump.sh/hal-cardano-foundation/docs/830981cc-283a-466c-b2db-829623049b3f/versions/2ccfe3cc-fcb1-4b7d-9e7a-159805986340, the pushed change

Cardano Wallet Backend API documentation , the documentation

[abailly]

Alternatively, drop bump.sh? There are local or browser-based tools that can produce documentation out of OpenApi specs, and we might want to centralise documentation on c-w anyway?

[paolino]

Alternatively, drop bump.sh? There are local or browser-based tools that can produce documentation out of OpenApi specs, and we might want to centralise documentation on c-w anyway?

We are already hosting them, docs. I think bump.sh was chosen additionally to report the diffs between releases.

[abailly]

Can someone shed some lights on the reasons we are using bump.sh and the value it provides if we are already hosting the documentation? @HeinrichApfelmus perhaps?

[HeinrichApfelmus]

Can someone shed some lights on the reasons we are using bump.sh and the value it provides if we are already hosting the documentation?

The main value of the bump.sh web service is that it gives us diffs for the HTTP API, i.e. the service allows people to query for changes to the API, such as

https://bump.sh/hal-cardano-foundation/doc/cardano-wallet-backend/changes/

In the past, the Daedalus front-end team has used this to assess the effort required to update to a new cardano-wallet version.

[abailly]

Would it be a big loss if we just removed this step? It's just more maintenance burden for very little added value. After all, if you need a diff of the API you could just do a diff on the swagger file.

[HeinrichApfelmus]

Not sure.

If I were a user of cardano-wallet, then bump.sh would be valuable to me, because the diffs are ready-made, convenient to parse visually, and can also span multiple versions.

In comparison, running vanilla diff on my own machine is more effort, and parsing the swagger.yaml file by eye is more difficult.

Our use of bump.sh was introduce in a time before I joined the team, so I don't have a particularly strong opinion on it, but I did feel that it's useful.

[paolino]

The UI is somehow inconsistent.

Browsing https://bump.sh/hal-cardano-foundation/doc/cardano-wallet-backend/changes I can select the differences between current and previous gives https://bump.sh/hal-cardano-foundation/doc/cardano-wallet-backend/compare/main..07b56143-5c5d-4e6e-87fc-7f352f53fcf3

This looks correct to me because git diff v2025-01-07 v2025-01-09 actually contains:

@@ -5115,6 +5115,7 @@ x-errTxNotInNodeEra: &errTxNotInNodeEra
 x-errBalanceTxConflictingNetworks: &errBalanceTxConflictingNetworks
   <<: *responsesErr
   title: balance_tx_conflicting_networks
+  deprecated: true # TODO: Remove this error as soon as bump.sh allows us to
   properties:
     message:
       type: string 

But if I jump to the documentation https://bump.sh/hal-cardano-foundation/doc/cardano-wallet-backend, I see and can retrieve the only the previous version only

Also the deployment page is pretty clear that everything worked

• the status is released
• the diff is correct
• the version is wrong

[paolino]

I have found a tool we can use to eliminate bump.sh . This is the result of diffing v2025-01-07 with v2025-01-09:

### New Endpoints: None
-----------------------

### Deleted Endpoints: None
---------------------------

### Modified Endpoints: 1
-------------------------
POST /wallets/{walletId}/transactions-balance
- Responses changed
  - Modified response: 403
    - Content changed
      - Modified media type: application/json
        - Schema changed
          - Property 'OneOf' changed
            - Modified schema: subschema ##3: balance_tx_conflicting_networks
              - Deprecated changed from false to true

Rendered as

New Endpoints: None

---

Deleted Endpoints: None

---

Modified Endpoints: 1

---

POST /wallets/{walletId}/transactions-balance

• Responses changed
  • Modified response: 403
    • Content changed
      • Modified media type: application/json
        • Schema changed
          • Property 'OneOf' changed
            • Modified schema: subschema #3: balance_tx_conflicting_networks
              • Deprecated changed from false to true

It's not great as GH, in the release page as well interprets #3 as a link to a PR

[abailly]

That looks promising @paolino ! The question is: what to do with this information?

bump.sh is supposed to provide informations to users of the API, telling them when things change, but I wonder who among our users is aware of it: I could not find any link to https://bump.sh/hal-cardano-foundation/doc/cardano-wallet-backend in our codebase, but perhaps I missed something obvious?

[paolino]

That looks promising @paolino ! The question is: what to do with this information?

bump.sh is supposed to provide informations to users of the API, telling them when things change, but I wonder who among our users is aware of it: I could not find any link to https://bump.sh/hal-cardano-foundation/doc/cardano-wallet-backend in our codebase, but perhaps I missed something obvious?

Yes, that the documentation is not good as it should be.

The big advantage of bump.sh is that you can compute any release API difference on the fly. OTOH they are easy to sum up.

[abailly]

Yes, that the documentation is not good as it should be.

Not sure I get it: Do you mean I overlooked something in the documentation? Or that the documentation is actually missing the part on bump.sh? Or something else?

[paolino]

Yes, that the documentation is not good as it should be.

Not sure I get it: Do you mean I overlooked something in the documentation? Or that the documentation is actually missing the part on bump.sh? Or something else?

That the documentation is actually missing that part. OTOH one can learn how bump.sh works on his own. If we fix it.

[paolino]

It's decided we drop bump.sh in favor of inlining the API difference with the previous release in the release notes