refactor(docs): clean up Versioning page #12084
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Codecov Report
@@ Coverage Diff @@
## edge #12084 +/- ##
==========================================
- Coverage 73.99% 73.99% -0.01%
==========================================
Files 2197 2197
Lines 60839 60839
Branches 6456 6456
==========================================
- Hits 45017 45016 -1
Misses 14300 14300
- Partials 1522 1523 +1
Flags with carried forward coverage won't be shown. Click here to find out more.
|
SyntaxColoring
approved these changes
Feb 1, 2023
Comment on lines
+13
to
+15
| The major version of the API increases whenever there are significant structural or behavioral changes to protocols. For instance, major version 2 of the API was introduced because it required protocols to have a ``run`` function that takes a ``protocol`` argument rather than importing the ``robot``, ``instruments``, and ``labware`` modules. Protocols written with major version 1 of the API will not run without modification in major version 2. A similar level of structural change would require a major version 3. This documentation only deals with features found in major version 2 of the API; see the `archived version 1 documentation <https://docs.opentrons.com/v1/index.html>`_ for information on older protocols. | ||
|
|
||
| The minor version of the API increases whenever there is new functionality that might change the way a protocol is written, or when a behavior changes in one aspect of the API but does not affect all protocols. For instance, adding support for a new hardware module, adding new parameters for a function, or deprecating a feature would increase the minor version of the API. |
There was a problem hiding this comment.
Hmm. What do we mean here by "deprecating a feature"? Actually removing it and making it unavailable, or just stating that we discourage it?
There was a problem hiding this comment.
We do need to standardize that terminology, but the facts on the ground are that we have completely removed features and not bumped major version. Although perhaps "completely" overstates it, if you can lower your apiLevel and get that behavior "back".
jwwojak
reviewed
Feb 1, 2023
jwwojak
reviewed
Feb 2, 2023
jwwojak
reviewed
Feb 2, 2023
jwwojak
reviewed
Feb 2, 2023
jwwojak
reviewed
Feb 2, 2023
jwwojak
reviewed
Feb 2, 2023
|
|
||
| Version specification is required by the system. If you do not specify a target API version, you will not be able to simulate or run your protocol. |
There was a problem hiding this comment.
I'd suggest this, "An API version level is required. You cannot simulate or run a protocol if you do not specify an API version."
The text "API version level" echos apiLevel but does it in readable text.
And we can get rid of the "will not be able to" construction in the 2nd sentence. Plus, flipping the sentence around gets rid of the comma.
jwwojak
reviewed
Feb 2, 2023
jwwojak
reviewed
Feb 2, 2023
jwwojak
reviewed
Feb 2, 2023
jwwojak
approved these changes
Feb 2, 2023
y3rsh
added a commit
that referenced
this pull request
Feb 7, 2023
* edge: (116 commits) feat(system-server): add sqlite database and barebones HTTP server (#12085) feat(ot3): add enableOT3FirmwareUpdates feature flag to gate firmware update functionality. (#12102) feat(app): add bare bones hardware section to protocol details (#12099) feat(app): Support failed calibrations in the calibration wizard (#12092) refactor(docs): clean up Versioning page (#12084) refactor(robot-server): Make run and protocol limits configurable at launch (#12094) feat(app): add robotServerVersion to display the current robot software version (#12096) fix(hardware): do not track tip motor positions (#12093) feat(engine): allow calibrateGripper command to save calibration data (#12046) feat(app, api-client, react-api-client): delete POC TLC calibration data from overflow menu (#12075) fix(api): actually update OT3 instrument calibration offset in cache instrument (#12089) fix(robot-server): correct the data returned from instruments endpoint (#12067) feat(api): add thermocycler plate lift to hardware controller (#12068) fix(app): reference moduleId from result not params (#12077) feat(app): create ODD protocol setup page (#12071) refactor(api): Deprecate presses and increment args when using PAPI pick_up_tip (#12079) fix(ot3): handle multiple responses for a tip action request (#12083) refactor(api): touch tip implementation for PAPIv2 engine core (#12053) refactor(app): Remove ssid parameter from OnDeviceRouteParams (#11930) fix(api): fix broken test in the api hardware controller (#12080) ...
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Overview
The Versioning page of the Python API docs was due for an editing pass.
Addresses RTC-55.
Test Plan
Proofread and check all reference links in sandbox for this PR.
Changelog
pair_with()Review requests
TC: Clean prose?
Eng: All feature descriptions and code are accurate?
Risk assessment
none, docs only