(docs): Add lakeFS-spec and lakeFS-SDK transaction differences

[maxmynter]

Closes https://github.com/aai-institute/MLOps-Engineering/issues/29

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (15c3526) 94.10% compared to head (78de589) 94.08%.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #252      +/-   ##
==========================================
- Coverage   94.10%   94.08%   -0.02%     
==========================================
  Files           5        5              
  Lines         407      406       -1     
  Branches       72       72              
==========================================
- Hits          383      382       -1     
  Misses         15       15              
  Partials        9        9              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[maxmynter]

I cannot directly comment on code not (yet) affected by this PR.

In the complete function of the LakeFSTransaction context class ( line 162 in the transactions.py ) we set self.fs._intrans = False. Is that necessary, since the __exit__ function of the Transaction parent class from fsspec already sets this flag to false after calling complete?

[nicholasjng]

In the complete function of the LakeFSTransaction context class ( line 162 in the transactions.py ) we set self.fs._intrans = False. Is that necessary, since the __exit__ function of the Transaction parent class from fsspec already sets this flag to false after calling complete?

I guess it's not necessary, but it does not hurt, either, so I'm unsure. If you can verify that this does not break any tests, I'm happy to see it removed.

[nicholasjng]

Suggested change

	- `lakeFS-SDK` transactions create an ephemeral branch, perform the operations in the context block on this branch and, upon exiting the context manager, merge it back into the source branch.
	- High-level `lakefs` SDK transactions create an ephemeral branch, perform the operations in the context block on that ephemeral branch and, upon exiting the context, merge it back into the source branch.

[AdrianoKF]

I would leave out the backticks (as mentioned above).

[nicholasjng]

Suggested change

	- `lakeFS-spec` transactions collect the actions and perform them one by one directly on the source branch once the context manager is exited. This allows, for example, multiple commits per transaction.
	- `lakeFS-spec` transactions collect the actions and perform them one by one directly on the source branch once the context manager is exited. This allows more flexible operations, for example, creating multiple commits per transaction.

[AdrianoKF]

As above, no backticks.

[AdrianoKF]

The placement of this callout is a bit (visually) unfortunate, IMO, since it separates the last sentence of the introduction from the rest, creating a sort-of orphan.

Instead of a list inside the callout, I would simply have two sentences (maybe with * * emphasis on the package names).

In case you want to keep the list, please include a blank link before the first list item, otherwise the list does not render correctly in Mkdocs.

[AdrianoKF]

I would leave out the backticks (as mentioned above).

[AdrianoKF]

As above, no backticks.

[AdrianoKF]

Suggested change

	- `lakeFS-spec` transactions collect the actions and perform them one by one directly on the source branch once the context manager is exited. This allows, for example, multiple commits per transaction.
	- `lakeFS-spec` transactions collect the actions and perform them one by one directly on the source branch once the context manager is exited. This allows for a more fine-grained control over the versioning operations performed. For example, multiple commits can be performed as part of a single transaction.