From 2526e51a41ffb13818ade03cbabb9742bb977113 Mon Sep 17 00:00:00 2001 From: hannah Date: Tue, 5 Sep 2023 22:39:43 -0400 Subject: [PATCH 1/5] ported communications guide to development guide --- doc/devel/communication_guide.rst | 121 ++++++++++++++++++++++++++++++ doc/devel/index.rst | 1 + 2 files changed, 122 insertions(+) create mode 100644 doc/devel/communication_guide.rst diff --git a/doc/devel/communication_guide.rst b/doc/devel/communication_guide.rst new file mode 100644 index 000000000000..0fc8559fbe62 --- /dev/null +++ b/doc/devel/communication_guide.rst @@ -0,0 +1,121 @@ +.. _communications-guidelines: + +======================== +Communication guidelines +======================== + +These guidelines are applicable when acting as a representative of Matplotlib, +for example at sprints or when giving official talks or tutorials, and in any +community venue managed by Matplotlib. + +.. _communication-channels: + +Official communication channels +=============================== +The following venues are managed by Matplotlib maintainers and contributors: + +* https://github.com/matplotlib/matplotlib +* https://discourse.matplotlib.org/ +* https://gitter.im/matplotlib/ +* https://github.com/matplotlib/matplotblog + + +Social Media +------------ + +* https://twitter.com/matplotlib +* https://instagram.com/matplotart/ +* https://www.tiktok.com/@matplotart + + +Mailing lists +---------------- + +* https://mail.python.org/mailman/listinfo/matplotlib-announce +* https://mail.python.org/mailman/listinfo/matplotlib-users +* https://mail.python.org/mailman/listinfo/matplotlib-devel + +.. _social-media-coordination: + +Social media coordination +------------------------- +team mailing list: matplotlib-social@numfocus.org +public chat room: https://gitter.im/matplotlib/community + +Content guidelines +==================== +Communication on official channels, such as the Matplotlib homepage or on +Matplotlib social accounts, should conform to the following standards: + +- be primarily about Matplotlib, 3rd party packages, and visualizations made with Matplotlib +- also acceptable topics: Python, Visualization, NumFOCUS libraries +- no gratuitous disparaging of other visualization libraries and tools; criticism is acceptable so long as it serves a constructive purpose +- follow visualization communication best practices + - don't share non-expert visualizations when it could be harmful + - put on meeting agenda when answer isn't clearly to hold off on sharing. + - clearly state when the visualization data/conclusions cannot be verified + - do not rely on machine translations for sensitive visualizations + - example: https://twitter.com/matplotlib/status/1244178154618605568 +- verify sourcing of content (especially on instagram & blog) + - Instagram/blog: ensure mpl has right to repost/share content + - make sure content is clearly cited + - example: a tutorial using someone else’s example clearly cites the original source +- Limited self/corporate promotion is acceptable, but should be no more than about a quarter of the content of the blog/discourse post. +- if you think content is borderline, ask on the :ref:`_social-media-coordination` channels before publishing it +- acceptable image guide: + - keep it geared towards science/data visualization, and non-controversial images + - must be conform to the guidelines of all sites it may be posed on: + - https://help.twitter.com/en/rules-and-policies/twitter-rules + - https://help.instagram.com/477434105621119 + +Accessibility +------------- +Images in communications should be as accessible as possible: + +- add alt text to images and videos when the platform allows + - https://webaim.org/techniques/alttext/ + - https://medium.com/nightingale/writing-alt-text-for-data-visualization-2a218ef43f81 +- warn on bright, strobing, images & turn off autoplay if possible +- for images made by the social media team: + - make graphic perceivable to people who cannot perceive color well, due to color-blindness or low vision + - do not make bright, strobing images + - more guidelines at https://webaim.org/techniques/images/ + + + +Social media account information +================================ + +Behavior +-------- +When acting as a representative of the library, keep responses polite, and assume +user statements are in good faith unless they violate the [Code of Conduct](https://www.python.org/psf/conduct/) + +Persona +------- +On social media, Matplotlib: + +* Is a sentient visualization library, so talks about itself as a we, us, our, and it. Avoids talking about itself in the 3rd person. +* Is very earnest, eager to please, and aims to be patient & painfully oblivious to snark and sarcasm. +* Gets over-excited over shiny visualizations - lots of emojis and the like - and encourages folks to share their work. +* Highlights various parts of the library, especially the more obscure bits and bobbles. +* Acknowledges that it is a sometimes frustrating tangle of bits & bobbles that can confuse even the folks who work on it & signal boosts their confuzzlment. + +Social graph +------------ +- only follow organizations/projects - mostly NumFocus projects + - especially 3rd party packages + - should at least be visualization related + - sponsors are also acceptable +- do not follow individual accounts for any reason (even maintainers/project leads/Guido!) + +Recurrent social campaigns +-------------------------- + +- Release Announcements + - Highlight new features & major deprecations + - Link to download/install instructions + - Ask folks to try it out. +- signal boost third party packages +- GSOC work during GSOC recruiting and work times +- John Hunter Excellence in Plotting, submission and winners diff --git a/doc/devel/index.rst b/doc/devel/index.rst index 2b358595255b..9537859c107a 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -167,6 +167,7 @@ Policies and guidelines :maxdepth: 1 release_guide + communication_guide min_dep_policy MEP/index From 22e2fe51eb3f1bc73743357c4c28d6d07335ed4a Mon Sep 17 00:00:00 2001 From: hannah Date: Wed, 6 Sep 2023 00:43:43 -0400 Subject: [PATCH 2/5] updated communications guidelines with current information Fix section title formatting Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> --- doc/devel/communication_guide.rst | 226 ++++++++++++++++++-------- doc/users/project/code_of_conduct.rst | 2 +- 2 files changed, 158 insertions(+), 70 deletions(-) diff --git a/doc/devel/communication_guide.rst b/doc/devel/communication_guide.rst index 0fc8559fbe62..2b8e9f384037 100644 --- a/doc/devel/communication_guide.rst +++ b/doc/devel/communication_guide.rst @@ -8,28 +8,38 @@ These guidelines are applicable when acting as a representative of Matplotlib, for example at sprints or when giving official talks or tutorials, and in any community venue managed by Matplotlib. + + .. _communication-channels: Official communication channels =============================== The following venues are managed by Matplotlib maintainers and contributors: -* https://github.com/matplotlib/matplotlib -* https://discourse.matplotlib.org/ -* https://gitter.im/matplotlib/ -* https://github.com/matplotlib/matplotblog +* library and docs: https://github.com/matplotlib/matplotlib +* forum: https://discourse.matplotlib.org/ +* chat: `https://matrix.to/#/#matplotlib:matrix.org `_ +* blog: https://blog.scientific-python.org/ - -Social Media +Social media ------------ +Active social media +^^^^^^^^^^^^^^^^^^^ + * https://twitter.com/matplotlib * https://instagram.com/matplotart/ + +Official accounts +^^^^^^^^^^^^^^^^^ +* https://bsky.app/profile/matplotlib.bsky.social +* https://fosstodon.org/@matplotlib * https://www.tiktok.com/@matplotart +* https://www.youtube.com/matplotlib Mailing lists ----------------- +------------- * https://mail.python.org/mailman/listinfo/matplotlib-announce * https://mail.python.org/mailman/listinfo/matplotlib-users @@ -39,83 +49,161 @@ Mailing lists Social media coordination ------------------------- -team mailing list: matplotlib-social@numfocus.org -public chat room: https://gitter.im/matplotlib/community +* Team mailing list: matplotlib-social@numfocus.org +* Public chat room: `https://matrix.to/#/#matplotlib_community:gitter.im `_ + + +Maintenance +----------- + +If you are interested in moderating the chat or forum or accessing the social +media accounts: + +* Matplotlib maintainers should reach out to the `community-manager`_. + +* Everyone else should send an email to matplotlib-social-admin@numfocus.org: + + * Introduce yourself - github handle and participation in the community. + * Describe the reason for wanting to moderate or contribute to social. + Content guidelines -==================== +================== + Communication on official channels, such as the Matplotlib homepage or on -Matplotlib social accounts, should conform to the following standards: - -- be primarily about Matplotlib, 3rd party packages, and visualizations made with Matplotlib -- also acceptable topics: Python, Visualization, NumFOCUS libraries -- no gratuitous disparaging of other visualization libraries and tools; criticism is acceptable so long as it serves a constructive purpose -- follow visualization communication best practices - - don't share non-expert visualizations when it could be harmful - - put on meeting agenda when answer isn't clearly to hold off on sharing. - - clearly state when the visualization data/conclusions cannot be verified - - do not rely on machine translations for sensitive visualizations - - example: https://twitter.com/matplotlib/status/1244178154618605568 -- verify sourcing of content (especially on instagram & blog) - - Instagram/blog: ensure mpl has right to repost/share content - - make sure content is clearly cited - - example: a tutorial using someone else’s example clearly cites the original source -- Limited self/corporate promotion is acceptable, but should be no more than about a quarter of the content of the blog/discourse post. -- if you think content is borderline, ask on the :ref:`_social-media-coordination` channels before publishing it -- acceptable image guide: - - keep it geared towards science/data visualization, and non-controversial images - - must be conform to the guidelines of all sites it may be posed on: - - https://help.twitter.com/en/rules-and-policies/twitter-rules - - https://help.instagram.com/477434105621119 +Matplotlib social accounts, should conform to the following standards. If you +are unsure if content that you would like to post or share meets these +guidelines, ask on the :ref:`social-media-coordination` channels before posting. + +General guidelines +------------------ + +* Focus on Matplotlib, 3rd party packages, and visualizations made with Matplotlib. +* These are also acceptable topics: + + * Visualization best practices and libraries. + * Projects and initiatives by NumFOCUS and Scientific Python. + * How to contribute to open source projects. + * Projects, such as scientific papers, that use Matplotlib. + +* No gratuitous disparaging of other visualization libraries and tools, but + criticism is acceptable so long as it serves a constructive purpose. + +* Follow communication best practices: + + * Do not share non-expert visualizations when it could cause harm: + + * e.g. https://twitter.com/matplotlib/status/1244178154618605568 + + * Clearly state when the visualization data/conclusions cannot be verified. + * Do not rely on machine translations for sensitive visualization. + +* Verify sourcing of content (especially on instagram & blog): + + * Instagram/blog: ensure mpl has right to repost/share content + * Make sure content is clearly cited: + + * e.g. a tutorial reworking an example must credit the original example + +* Limited self/corporate promotion is acceptable. + + * Should be no more than about a quarter of the content. + +Visual media guidelines +----------------------- + +Visual media, such as images and videos, must not violate the +:ref:`code of conduct `, nor any platform's rules. +Specifically: + +* Visual media must conform to the guidelines of all sites it may be posted on: + + * https://help.twitter.com/en/rules-and-policies/twitter-rules + * https://help.instagram.com/477434105621119 + +* Emphasize the visualization techniques demonstrated by the visual media. +* Clearly state that sharing is not an endorsement of the content. + + * e.g. bitcoin related visualizations Accessibility -------------- -Images in communications should be as accessible as possible: +^^^^^^^^^^^^^ -- add alt text to images and videos when the platform allows - - https://webaim.org/techniques/alttext/ - - https://medium.com/nightingale/writing-alt-text-for-data-visualization-2a218ef43f81 -- warn on bright, strobing, images & turn off autoplay if possible -- for images made by the social media team: - - make graphic perceivable to people who cannot perceive color well, due to color-blindness or low vision - - do not make bright, strobing images - - more guidelines at https://webaim.org/techniques/images/ +Visual media in communications should be made as accessible as possible: +* Add alt text to images and videos when the platform allows: + * `alt text for data viz `_ + * `general alt text guide `_ -Social media account information -================================ +* Warn on bright, strobing, images & turn off autoplay if possible. +* For images and videos made by the social media team: + + * Make graphic perceivable to people who cannot perceive color well due to + color-blindness, low vision, or any other reason. + + * Do not make bright, strobing images. + * More guidelines at https://webaim.org/techniques/images/. -Behavior --------- -When acting as a representative of the library, keep responses polite, and assume -user statements are in good faith unless they violate the [Code of Conduct](https://www.python.org/psf/conduct/) + +Social media +============ + +Please follow these guidelines to maintain a consistent brand identity across +platforms. Persona ------- On social media, Matplotlib: -* Is a sentient visualization library, so talks about itself as a we, us, our, and it. Avoids talking about itself in the 3rd person. -* Is very earnest, eager to please, and aims to be patient & painfully oblivious to snark and sarcasm. -* Gets over-excited over shiny visualizations - lots of emojis and the like - and encourages folks to share their work. -* Highlights various parts of the library, especially the more obscure bits and bobbles. -* Acknowledges that it is a sometimes frustrating tangle of bits & bobbles that can confuse even the folks who work on it & signal boosts their confuzzlment. +* Acts as a sentient visualization library, so talks about itself as a we, us, + our, and it. Avoids talking about itself in the 3rd person. Never uses 1st person. +* Is very earnest, eager to please, and aims to be patient & painfully oblivious + to snark and sarcasm. +* Gets over-excited over shiny visualizations - lots of emojis and the like - + and encourages folks to share their work. +* Highlights various parts of the library, especially the more obscure bits and + bobbles. +* Acknowledges that it is a sometimes frustrating tangle of bits & bobbles that + can confuse even the folks who work on it & signal boosts their confuzzlment. + + +Behavior +-------- +When acting as a representative of the library, keep responses polite and assume +user statements are in good faith unless they violate the :ref:`code of conduct `. Social graph ------------ -- only follow organizations/projects - mostly NumFocus projects - - especially 3rd party packages - - should at least be visualization related - - sponsors are also acceptable -- do not follow individual accounts for any reason (even maintainers/project leads/Guido!) - -Recurrent social campaigns --------------------------- - -- Release Announcements - - Highlight new features & major deprecations - - Link to download/install instructions - - Ask folks to try it out. -- signal boost third party packages -- GSOC work during GSOC recruiting and work times -- John Hunter Excellence in Plotting, submission and winners + +Only follow **organizations and projects**, do not follow individual accounts for +any reason, even maintainers/project leads/famous Python people! + +Following these types of accounts is encouraged: + +* NumFocus and Scientific Python projects +* 3rd party packages +* Visualization related projects and organizations +* Open Source community projects +* Sponsors + +Recurring campaigns +------------------- + +Typically the social media accounts will promote the following: + +* Matplotlib releases: + + * Highlight new features & major deprecations + * Link to download/install instructions + * Ask folks to try it out. + +* `third party packages `_ +* NumFocus/Scientific Python/open source visualization project releases +* GSOC/GSOD recruiting and progress + +Retired campaigns +^^^^^^^^^^^^^^^^^ +* John Hunter Excellence in Plotting, submission and winners + +.. _community-manager: https://matplotlib.org/governance/people.html#deputy-project-leads diff --git a/doc/users/project/code_of_conduct.rst b/doc/users/project/code_of_conduct.rst index 8deda909bd4c..ac8b268a4e30 100644 --- a/doc/users/project/code_of_conduct.rst +++ b/doc/users/project/code_of_conduct.rst @@ -1,4 +1,4 @@ -.. code_of_conduct +.. _code_of_conduct: ==================================== Contributor Covenant Code of Conduct From d6592361ca9f663178ddb3d2f595c05233626314 Mon Sep 17 00:00:00 2001 From: hannah Date: Thu, 5 Oct 2023 17:31:11 -0400 Subject: [PATCH 3/5] process for changing guidelines --- doc/devel/communication_guide.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/doc/devel/communication_guide.rst b/doc/devel/communication_guide.rst index 2b8e9f384037..e21968a67f68 100644 --- a/doc/devel/communication_guide.rst +++ b/doc/devel/communication_guide.rst @@ -206,4 +206,15 @@ Retired campaigns ^^^^^^^^^^^^^^^^^ * John Hunter Excellence in Plotting, submission and winners + +Changing the guidelines +======================= + +As the person tasked with implementing communications, the `community-manager`_ +should be alerted to proposed changes to the communications guidelines. Similarly, +specific platform guidelines (e.g. twitter, instagram) should be reviewed by the +person responsible for that platform, when different from the community manager. +If there is no consensus, decisions about communications guidelines revert to +the community manager. + .. _community-manager: https://matplotlib.org/governance/people.html#deputy-project-leads From b9ebda8353eb9f82986748169dcbbdde091aed95 Mon Sep 17 00:00:00 2001 From: hannah Date: Sat, 23 Sep 2023 21:27:43 -0400 Subject: [PATCH 4/5] update release guide to use contact info --- doc/_static/mpl.css | 19 +++++++++++++++++++ doc/devel/communication_guide.rst | 11 +++++++---- doc/devel/release_guide.rst | 25 ++++++++++++------------- doc/users/release_notes.rst | 1 + 4 files changed, 39 insertions(+), 17 deletions(-) diff --git a/doc/_static/mpl.css b/doc/_static/mpl.css index 45ecb21d5511..a37fb76a0436 100644 --- a/doc/_static/mpl.css +++ b/doc/_static/mpl.css @@ -161,3 +161,22 @@ div.wide-table table th.stub { font-style: italic; font-size: large; } + + +.checklist { + list-style: none; + padding: 0; + margin: 0; +} +.checklist li { + margin-left: 24px; + padding-left: 23px; + margin-right: 6px; +} +.checklist li:before { + content: "\2610\2001"; + margin-left: -24px; +} +.checklist li p { + display: inline; +} diff --git a/doc/devel/communication_guide.rst b/doc/devel/communication_guide.rst index e21968a67f68..b9fa301c0e46 100644 --- a/doc/devel/communication_guide.rst +++ b/doc/devel/communication_guide.rst @@ -9,7 +9,6 @@ for example at sprints or when giving official talks or tutorials, and in any community venue managed by Matplotlib. - .. _communication-channels: Official communication channels @@ -21,6 +20,8 @@ The following venues are managed by Matplotlib maintainers and contributors: * chat: `https://matrix.to/#/#matplotlib:matrix.org `_ * blog: https://blog.scientific-python.org/ +.. _social-media: + Social media ------------ @@ -38,12 +39,14 @@ Official accounts * https://www.youtube.com/matplotlib +.. _mailing-lists: + Mailing lists ------------- -* https://mail.python.org/mailman/listinfo/matplotlib-announce -* https://mail.python.org/mailman/listinfo/matplotlib-users -* https://mail.python.org/mailman/listinfo/matplotlib-devel +* `matplotlib-announce@python.org `_ +* `matplotlib-users@python.org `_ +* `matplotlib-devel@python.org `_ .. _social-media-coordination: diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst index 2bbe589282a3..4adc4546e879 100644 --- a/doc/devel/release_guide.rst +++ b/doc/devel/release_guide.rst @@ -455,22 +455,21 @@ Due to branch protections for the ``main`` branch, this is merged via a standard request, though the PR cleanliness status check is expected to fail. The PR should not be squashed because the intent is to merge the branch histories. -Announcing -========== +Publicize this release +====================== -The final step is to announce the release to the world. A short -version of the release notes along with acknowledgments should be sent to +After the release is published to PyPI and conda, it should be announced +through our communication channels: -- matplotlib-users@python.org -- matplotlib-devel@python.org -- matplotlib-announce@python.org - -In addition, announcements should be made on social networks (e.g., Twitter via the -``@matplotlib`` account, any other via personal accounts). - -Add a release announcement to the ``mpl-brochure-site`` "News" section of -``docs/body.html``, linking to the discourse page for the announcement. +.. rst-class:: checklist +* Send a short version of the release notes and acknowledgments to all the :ref:`mailing-lists` +* Post highlights and link to :ref:`What's new ` on the + active :ref:`social media accounts ` +* Add a release announcement to the "News" section of + `matplotlib.org `_ by editing + ``docs/body.html``. Link to the auto-generated announcement discourse post, + which is in `Announcements > matplotlib-announcements `_. Conda packages ============== diff --git a/doc/users/release_notes.rst b/doc/users/release_notes.rst index 7862305af65e..c3cd17ce59ea 100644 --- a/doc/users/release_notes.rst +++ b/doc/users/release_notes.rst @@ -1,6 +1,7 @@ .. redirect-from:: /api/api_changes_old .. redirect-from:: /users/whats_new_old +.. _release-notes: ============= Release notes From 0887901f3e95115589d653e24430845df2388872 Mon Sep 17 00:00:00 2001 From: hannah Date: Thu, 5 Oct 2023 14:14:10 -0400 Subject: [PATCH 5/5] coding guide --- doc/devel/coding_guide.rst | 9 --------- 1 file changed, 9 deletions(-) diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst index 49f35e3ad13e..0385d6d388f0 100644 --- a/doc/devel/coding_guide.rst +++ b/doc/devel/coding_guide.rst @@ -1,12 +1,3 @@ -.. raw:: html - - - .. _pr-guidelines: ***********************