Skip to content

DOC: Document policy on colormaps and styles #28815

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 17, 2024
Merged

DOC: Document policy on colormaps and styles #28815

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 19 additions & 7 deletions doc/devel/api_changes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,8 @@ if the added benefit is worth the effort of adapting existing code.

Because we are a visualization library, our primary output is the final
visualization the user sees; therefore, the appearance of the figure is part of
the API and any changes, either semantic or :ref:`aesthetic <color_changes>`,
are backwards-incompatible API changes.

.. toctree::
:hidden:

color_changes.rst
the API and any changes, either semantic or aesthetic, are backwards-incompatible
API changes.


Add new API and features
Expand All @@ -37,6 +32,23 @@ take particular care when adding new API:
__ https://emptysqua.re/blog/api-evolution-the-right-way/#adding-parameters


Add or change colormaps, color sequences, and styles
----------------------------------------------------
Visual changes are considered an API break. Therefore, we generally do not modify
existing colormaps, color sequences, or styles.

We put a high bar on adding new colormaps and styles to prevent excessively growing
them. While the decision is case-by-case, evaluation criteria include:

- novelty: Does it support a new use case? e.g. slight variations of existing maps,
sequences and styles are likely not accepted.
- usability and accessibility: Are colors of sequences sufficiently distinct? Has
colorblindness been considered?
- evidence of wide spread usage: for example academic papers, industry blogs and
whitepapers, or inclusion in other visualization libraries or domain specific tools
- open license: colormaps, sequences, and styles must have a BSD compatible license
(see :ref:`license-discussion`)

.. _deprecation-guidelines:

Deprecate API
Expand Down
136 changes: 0 additions & 136 deletions doc/devel/color_changes.rst
View file
Open in desktop

This file was deleted.