matplotlib · noatamir · May 23, 2022 · Jun 16, 2022 · Jun 30, 2022 · Jun 30, 2022
diff --git a/doc/devel/git_workflows.rst b/doc/devel/git_workflows.rst
@@ -0,0 +1,44 @@
+
+.. _git_workflows:
+
+Git workflows
+=============
+
+When reviewing contributions, we sometime refer to this page to offer more detailed git workflows.
+
+.. _git_rebase:
+
+Rebase
+^^^^^^
+
+If you want to rebase, the first thing to do is to squash all your commits into one, which will make the job easier.
+Make sure you are in the PR branch, then to rebase do::
+
-If you want to rebase, the first thing to do is to squash all your commits into one, which will make the job easier.
-Make sure you are in the PR branch, then to rebase do::
+If you want to rebase, the first thing to do is to make a backup branch::
+
+$ git checkout my-working-branch
+$ git checkout -b backup-my-working-branch
+$ checkout my-working-branch
+
+If you mess anything up, you can always get back to where you were pre-rebase by doing::
+
+$ git checkout my-working-branch
+$ git reset --hard backup-my-working-branch
+
+Next, we suggest you squash all your commits into one, which will make the rebase easier.
+Make sure you are in the PR branch, then to rebase do::
+
-If you want to rebase, the first thing to do is to squash all your commits into one, which will make the job easier.
-Make sure you are in the PR branch, then to rebase do::
+If you want to rebase, the first thing to do is to make a backup branch::
+
+$ git checkout my-working-branch
+$ git checkout -b backup-my-working-branch
+$ checkout my-working-branch
+
+If you mess anything up, you can always get back to where you were pre-rebase by doing::
+
+$ git checkout my-working-branch
+$ git reset --hard backup-my-working-branch
+
+Next, we suggest you squash all your commits into one, which will make the rebase easier.
+Make sure you are in the PR branch, then to rebase do::
+
+$ git rebase --interactive upstream/main
+
+
+Git opens the last commits you made in our terminal editor (often it's vim) and you need to follow the instructions in
+the file. Basically replace 'pick' by 'fixup' (or simply 'f') in all but the first commit (exit vim using `:wq` to
+write/save and quite). Then update your main branch from upstream, change back to the PR branch and do::
-Git opens the last commits you made in our terminal editor (often it's vim) and you need to follow the instructions in
-the file. Basically replace 'pick' by 'fixup' (or simply 'f') in all but the first commit (exit vim using `:wq` to
-write/save and quite). Then update your main branch from upstream, change back to the PR branch and do::
+Git opens the last commits you made in your editor (see `echo $EDITOR`) and you need to follow the instructions in the file. Basically replace 'pick' by 'fixup' in all but the first commit. When done, exit your editor.  
+
+Next, update your main branch from upstream::
-Git opens the last commits you made in our terminal editor (often it's vim) and you need to follow the instructions in
-the file. Basically replace 'pick' by 'fixup' (or simply 'f') in all but the first commit (exit vim using `:wq` to
-write/save and quite). Then update your main branch from upstream, change back to the PR branch and do::
+Git opens the last commits you made in your editor (see `echo $EDITOR`) and you need to follow the instructions in the file. Basically replace 'pick' by 'fixup' in all but the first commit. When done, exit your editor.  
+
+Next, update your main branch from upstream::
+
+$ git rebase main
+
-$ git rebase main
+$ git fetch upstream
+$ git rebase upstream/main
+
-$ git rebase main
+$ git fetch upstream
+$ git rebase upstream/main
+
+
+and if there are problems, do ``$ git status`` to see which files need fixing, then edit the files to fix up any
+conflicts (sections marked by "<<<") . When you are done with that::
+
+$ git add <the fixed files>
+$ git rebase --continue
+$ git push --force-with-lease origin HEAD
+
+If you have any problems, feel free to ask questions.
+
+PS.
+If at any point anything goes wrong, and you don't know what to do, just do::
+
+$ git rebase --abort
+
+and everything will go back to the way it was in the before ``$ git rebase`` times, and you can come back to your PR,
+or to `gitter`_, and ask us for help, or that we do the rebase for you 😉.
-$ git push --force-with-lease origin HEAD
-
-If you have any problems, feel free to ask questions.
-
-PS.
-If at any point anything goes wrong, and you don't know what to do, just do::
-
-$ git rebase --abort
-
-and everything will go back to the way it was in the before ``$ git rebase`` times, and you can come back to your PR,
-or to `gitter`_, and ask us for help, or that we do the rebase for you 😉.
+
+If at any point anything goes wrong, and you don't know what to do, just do::
+
+$ git rebase --abort
+
+and everything will go back to the way it was in the before ``$ git rebase``, and you can come back to your PR,
+or to `gitter`_, and ask us for help, or that we do the rebase for you 😉.
+
+If you finish the rebase, but it is _still_ wrong, you can still get back to your backup branch, as noted above.  
+
+When you think your PR has the right commits (look at `git log`) based on the latest upstream/main you can push to GitHub::
+
+$ git push --force-with-lease origin my-working-branch
+
-$ git push --force-with-lease origin HEAD
-
-If you have any problems, feel free to ask questions.
-
-PS.
-If at any point anything goes wrong, and you don't know what to do, just do::
-
-$ git rebase --abort
-
-and everything will go back to the way it was in the before ``$ git rebase`` times, and you can come back to your PR,
-or to `gitter`_, and ask us for help, or that we do the rebase for you 😉.
+
+If at any point anything goes wrong, and you don't know what to do, just do::
+
+$ git rebase --abort
+
+and everything will go back to the way it was in the before ``$ git rebase``, and you can come back to your PR,
+or to `gitter`_, and ask us for help, or that we do the rebase for you 😉.
+
+If you finish the rebase, but it is _still_ wrong, you can still get back to your backup branch, as noted above.  
+
+When you think your PR has the right commits (look at `git log`) based on the latest upstream/main you can push to GitHub::
+
+$ git push --force-with-lease origin my-working-branch
+
+
+.. _gitter: https://gitter.im/matplotlib/matplotlib
diff --git a/doc/devel/saved_replies.rst b/doc/devel/saved_replies.rst
@@ -0,0 +1,53 @@
+
+.. _saved_replies:
+
+Saved replies
+=============
+
+To consistently maintain respectful and welcoming communication, reduce potential bias and errors, consistently provide
+relevant information, and to avoid repitition, we decided to create a collection of saved replies for recurring project
+needs. As a an active Matplotlib contributor, consider storing some of these responses in your GitHub account’s
+`saved replies`_ as they might prove useful while reviewing issues and PRs, and otherwise supporting other community
+members. Some of the suggested saved replies can be long and detailed. This is because we aim to offer support without
+assuming the level of experience, or the intent the community member we are addressing might have. There is still room
+to tweak and personalize your  message if, for instance, some parts are redundant, require further information, or to
+offer further support. Using these replies is optional.
+
+.. _saved replies: https://github.com/settings/replies/
+
+Issues
+------
+
+Coming soon 😉
+
+Pull Requests
+-------------
+
+First Pull Request Merged
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: md
+
+    Hi-five ✋ on merging your first pull request to Matplotlib, @username! We hope you stick around and invite you to
+    continue to take an active part in Matplotlib! Your choices aren’t limited to programming 😉 – you can review pull
+    requests, help us stay on top of new and old issues, develop educational material, refresh our documentation, work
+    on our website, and so much more! For more info, check out: https://matplotlib.org/devdocs/devel/index
+
+    Did you know we have a monthly meeting 👥 for new contributors and a weekly meeting for the maintainers,
+    everyone is welcome to join both? You can find out more about our regular project meetings in this
+    [calendar page](https://scientific-python.org/calendars/).
+
+    Also, consider joining our [developer mailing list](https://mail.python.org/mailman/listinfo/matplotlib-devel) ✉️.
+    This is a great way to connect with other people in our community and be part of important conversations that
+    affect the development of Matplotlib.
+
+Rebase
+^^^^^^
+.. code-block:: md
+
+    Hi, it looks your code needs to be rebased to include changes that have since occurred in the main repository. Would
+    you like to do this yourself, or would you like us to do this for you? I’m asking because a rebase can get a bit
+    fiddly and not everyone likes doing them 😉
+
+    We documented [the rebase process here](https://matplotlib.org/devdocs/devel/git_workflows#rebase.html) Have a look and
+    let me know how you'd like to proceed.
diff --git a/doc/devel/triage.rst b/doc/devel/triage.rst
@@ -21,6 +21,19 @@ If you do not have enough GitHub permissions do something (e.g. add a
 label, close an issue), please leave a comment tagging
 ``@matplotlib/triageteam`` with your recommendations!
 
+Follow the saved replies guide for detailed instructions on how to
+use and contribute to our communication repository. The git workflows has a few detailed workflows which we often link
+to while reviewing code.
+=======
+use and contribute to our communication repository.
+
+.. toctree::
+   :maxdepth: 2
+
+   saved_replies.rst
+   git_workflows.rst
+
+
 Working on issues to improve them
 ---------------------------------