docs: Update release, docs readme files with info, corrections#5599
Open
camdecoster wants to merge 1 commit into
Open
docs: Update release, docs readme files with info, corrections#5599camdecoster wants to merge 1 commit into
camdecoster wants to merge 1 commit into
Conversation
emilykl
reviewed
May 19, 2026
Comment on lines
65
to
77
| ### Branches | ||
|
|
||
| Two different cases exist, whether you are documenting a feature already | ||
| released, or which has just been included but not yet released. | ||
|
|
||
| - Case of an already released feature: your changes can be deployed to the | ||
| documentation website as soon as they have been merged, and you should start | ||
| your branch off the `doc-prod` branch and open your pull request against this | ||
| `doc-prod` branch. | ||
| - Case of a new (not released yet) feature: start your branch / pull request | ||
| against the `main` branch. `main` and `doc-prod` will be synchronized at | ||
| release time, so that the documentation of the feature is only deployed when | ||
| it is available in a released version of `plotly.py`. |
Contributor
There was a problem hiding this comment.
@camdecoster I edited this section a bit for clarity, feel free to accept the below if accurate.
Suggested change
| it is available in a released version of `plotly.py`. | |
| ### Branching strategy | |
| - The `doc-prod` branch contains the live docs which are available on the website. As soon as a change is merged into `doc-prod`, the updated docs are deployed and made publicly available. | |
| - The `main` branch contains docs which have been written but are not ready to be released, such as for an upcoming feature in the next plotly.py release. | |
| When updating the docs, two workflows are possible: | |
| - In the case of updating the docs for an already-released feature: your changes can be deployed to the documentation website as soon as they have been merged, so you should branch off of the `doc-prod` branch and open your pull request into the `doc-prod` branch. | |
| - In the case of writing docs for a new (not-yet-released) feature: you should branch off `main` and open your pull request into `main`, so that the documentation of the feature is only deployed when it is available in a released version of `plotly.py`. The `main` branch will be merged into `doc-prod` at release time, as described below. |
emilykl
reviewed
May 19, 2026
| section of `RELEASE.md` for the full procedure. | ||
|
|
||
| > **Release prep:** When synchronizing `main` into `doc-prod` for a new | ||
| > release, update the `plotly==` version pin in `requirements.txt` to match |
Contributor
There was a problem hiding this comment.
Suggested change
| > release, update the `plotly==` version pin in `requirements.txt` to match | |
| > release, update the `plotly==` version pin in `doc/requirements.txt` to match |
emilykl
reviewed
May 19, 2026
| --- | ||
| ``` | ||
|
|
||
| The `plotly` metadata fields are the most important to get right: |
Contributor
There was a problem hiding this comment.
@camdecoster It's OK to manually edit these fields, right?
Contributor
There was a problem hiding this comment.
NVM I see this is addressed in the section below, maybe state here as well for clarity though.
emilykl
reviewed
May 19, 2026
| The filename follows the pattern `2019-07-03-<markdown-filename-without-extension>.html`. | ||
|
|
||
| First, create an account at https://account.mapbox.com/auth/signup Once that is done, navigate to https://account.mapbox.com/ and copy your "Default public token" to the file `doc/python/.mapbox_token` | ||
| > **Why the `2019-07-03-` prefix?** The downstream `graphing-library-docs` |
Contributor
There was a problem hiding this comment.
Ha, I was wondering this, thanks for adding the explanation
emilykl
reviewed
May 19, 2026
|
|
||
| | Event | What happens | | ||
| |-------|-------------| | ||
| | Pull request (any branch) | Tutorials are built and validated. The build artifact is uploaded but not deployed. | |
Contributor
There was a problem hiding this comment.
Is this correct? I'm not totally clear what 'tutorials' refers to.
Suggested change
| | Pull request (any branch) | Tutorials are built and validated. The build artifact is uploaded but not deployed. | | |
| | Pull request (any branch) | Tutorials (`*.md` files) are built and validated. The build artifact is uploaded but not deployed. | |
emilykl
approved these changes
May 19, 2026
Contributor
emilykl
left a comment
emilykl
left a comment
There was a problem hiding this comment.
LGTM, thanks @camdecoster for documenting this process!
This file contains hidden or 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Description of change
Update release and docs README files with expanded instructions, corrections of errors/typos.
Additional information (optional)
I recently released new docs for v6.7.0 and ran into some roadblocks. These updates are an attempt to clarify some steps to make this a bit easier.
Guidelines