Updating pandas pull request guide, with sending the PR directly to pandas, and with information about updating the pull request

Author: datapythonista

pandas/guide/_sources/pandas_pr.rst.txt

@@ -21,10 +21,23 @@ execute in your terminal:
 where `<your-function-or-method>` is for example `pandas.DataFrame.head`,
 `pandas.Series.tail` or `pandas.to_datetime`.
 
+The output of the script will show the final docstring. In many cases just a
+verbatim copy, but in some cases the docstring is implemented as a template,
+and reused by more than one method or function, and this is useful to see
+the final result.
+
+The output will also contain a list of issues with the docstring. Mainly style
+errors, where the docstring does not respect the convention. For example, a
+missing dot at the end of a sentence, a blank line where it should not be, etc.
+
+Finally, the output will also contain errors from running the examples.
+
+With few exceptions, you should fix all the errors before continuing.
+
 2. Visual validation of the docstring
 -------------------------------------
 
-The previous script validates things like the names of the sections, or
+The previous sprint validates things like the names of the sections, or
 that there are dots, spaces, or blank lines in the right side. But does
 not validate for typos, unclear sentences, or other mistakes. To validate
 them, as well as the visualization of your docstring in the pandas website
@@ -45,8 +58,8 @@ that can be opened with your web browser.
 -------------------------------------------------
 
 As the last validation, please show the html version of your docstring to a
-person in the sprint not involved in the changes to the docstring, and make
-sure they are able to fully understand it.
+person in the sprint not involved in the changes to that specific docstring,
+and make sure they are able to fully understand it.
 
 4. Commit your changes
 ----------------------
@@ -59,6 +72,10 @@ you are going to commit with:
 
     | ``git branch``
 
+If the current branch is `master`, do not commit your changes, as you can get
+into a situation where you need to undo your history in git, which is not
+straight forward.
+
 Then, follow the next steps:
 
     | ``git fetch upstream``
@@ -69,40 +86,47 @@ Then, follow the next steps:
 where `<modified-file(s)>` is the file where you made your changes (in rare
 cases it could be more than one file). And `<commit-message>` is a short
 description of your changes, starting by "DOC:" (e.g. "DOC: Improved the
-docstring of DataFrame.head()").
+docsting of DataFrame.head()").
 
-5. Push your changes to the pandas repository
----------------------------------------------
+5. Push your changes to pandas
+------------------------------
 
-You are now ready to send a pull request to the pandas repository, to get your
-changes reviewed.
+Once you committed your changes locally, you need to make them available to
+pandas maintainers, so they can add them to the main pandas repository.
 
-First, push your changes to your GitHub fork:
+The first step is to push your local changes to your own fork, so they are
+available online:
 
     | ``git push -u origin <your-branch-name>``
 
-Then, visit https://github.com/pandas-dev/pandas in your browser, and click
+Then, visit https://github.com/python-sprints/pandas in your browser, and click
 on the "Compare & pull request" button in the yellow box above the repository
 files.
 
-6. Update your pull request based on feedback
----------------------------------------------
+This will create a pull request, will be reviewed by other developers. It is
+unlikely that a pull request is accepted in its first version, so expect some
+comments on things that can be improved, from more senior pandas contributors.
 
-The pull request will be reviewed by other sprint participants and pandas
-developers. Based on those discussions, you might need to make additional
-changes. After making those changes, make sure to again validate the docstring
-(steps 1-3).
+For comments in your review, you can make new changes in your local branch for
+that pull request. And once you addressed all the comments, you can commit them
+and push again to your local branch. As you used the parameter `-u` in your
+first push, you can simply run:
 
-To update the pull request, you can commit the changes and push again to
-github. The pull request will automatically be updated:
+    | ``git push``
 
-    | ``git add <modified-file(s)>``
-    | ``git commit -m "<commit-message>"``
-    | ``git push -u origin <your-branch-name>``
+from your local branch, and the changes will be pushed to your remote branch.
+
+Updating your remote branch automatically updates the pull request, so you do
+not need to create a new pull request, or make any other changes in the one
+already created.
 
-`<commit-message>` can now be a short indication of what has been updated
-(e.g. "clarified the extended summary" or simply "updates based on feedback").
+If you want to add any clarification to your changes, or you think the reviewer
+misunderstood something, you can add a comment to the pull request.
 
-Once the reviewers are happy with the changes, a pandas developer will
-merge your pull request (this may take some time when many pull requests
-are opened during the sprint, so be patient with this).
+Do not feel discouraged by having more than one review requesting changes for
+the same pull request. While in the first contributions is normal to feel
+frustrated for getting feedback requesting changes, it is actually because of
+reviews that the open source software quality is very high. And also, it is
+probably the part of contributing to open source projects in which you will
+learn more. So, be patient and enjoy. And feel free to provide constructive
+feedback in other contributors pull requests too.

pandas/guide/pandas_pr.html

@@ -57,6 +57,15 @@ <h2>1. Validate that your docstring does not have technical errors<a class="head
 </div></blockquote>
 <p>where <cite>&lt;your-function-or-method&gt;</cite> is for example <cite>pandas.DataFrame.head</cite>,
 <cite>pandas.Series.tail</cite> or <cite>pandas.to_datetime</cite>.</p>
+<p>The output of the script will show the final docstring. In many cases just a
+verbatim copy, but in some cases the docstring is implemented as a template,
+and reused by more than one method or function, and this is useful to see
+the final result.</p>
+<p>The output will also contain a list of issues with the docstring. Mainly style
+errors, where the docstring does not respect the convention. For example, a
+missing dot at the end of a sentence, a blank line where it should not be, etc.</p>
+<p>Finally, the output will also contain errors from running the examples.</p>
+<p>With few exceptions, you should fix all the errors before continuing.</p>
 </div>
 <div class="section" id="visual-validation-of-the-docstring">
 <h2>2. Visual validation of the docstring<a class="headerlink" href="#visual-validation-of-the-docstring" title="Permalink to this headline">¶</a></h2>
@@ -80,8 +89,8 @@ <h2>2. Visual validation of the docstring<a class="headerlink" href="#visual-val
 <div class="section" id="validate-that-the-docstring-is-clear-to-others">
 <h2>3. Validate that the docstring is clear to others<a class="headerlink" href="#validate-that-the-docstring-is-clear-to-others" title="Permalink to this headline">¶</a></h2>
 <p>As the last validation, please show the html version of your docstring to a
-person in the sprint not involved in the changes to the docstring, and make
-sure they are able to fully understand it.</p>
+person in the sprint not involved in the changes to that specific docstring,
+and make sure they are able to fully understand it.</p>
 </div>
 <div class="section" id="commit-your-changes">
 <h2>4. Commit your changes<a class="headerlink" href="#commit-your-changes" title="Permalink to this headline">¶</a></h2>
@@ -94,6 +103,9 @@ <h2>4. Commit your changes<a class="headerlink" href="#commit-your-changes" titl
 <div class="line"><code class="docutils literal"><span class="pre">git</span> <span class="pre">branch</span></code></div>
 </div>
 </div></blockquote>
+<p>If the current branch is <cite>master</cite>, do not commit your changes, as you can get
+into a situation where you need to undo your history in git, which is not
+straight forward.</p>
 <p>Then, follow the next steps:</p>
 <blockquote>
 <div><div class="line-block">
@@ -108,12 +120,12 @@ <h2>4. Commit your changes<a class="headerlink" href="#commit-your-changes" titl
 description of your changes, starting by “DOC:” (e.g. “DOC: Improved the
 docsting of DataFrame.head()”).</p>
 </div>
-<div class="section" id="push-your-changes-to-the-sprint-repository">
-<h2>5. Push your changes to the sprint repository<a class="headerlink" href="#push-your-changes-to-the-sprint-repository" title="Permalink to this headline">¶</a></h2>
-<p>Before sending the pull request to the pandas core developers, you will send
-it to the sprint repository. Where more experienced contributors will review
-it, and suggest changes if needed.</p>
-<p>First, push your changes to your GitHub fork:</p>
+<div class="section" id="push-your-changes-to-pandas">
+<h2>5. Push your changes to pandas<a class="headerlink" href="#push-your-changes-to-pandas" title="Permalink to this headline">¶</a></h2>
+<p>Once you committed your changes locally, you need to make them available to
+pandas maintainers, so they can add them to the main pandas repository.</p>
+<p>The first step is to push your local changes to your own fork, so they are
+available online:</p>
 <blockquote>
 <div><div class="line-block">
 <div class="line"><code class="docutils literal"><span class="pre">git</span> <span class="pre">push</span> <span class="pre">-u</span> <span class="pre">origin</span> <span class="pre">&lt;your-branch-name&gt;</span></code></div>
@@ -122,8 +134,31 @@ <h2>5. Push your changes to the sprint repository<a class="headerlink" href="#pu
 <p>Then, visit <a class="reference external" href="https://github.com/python-sprints/pandas">https://github.com/python-sprints/pandas</a> in your browser, and click
 on the “Compare &amp; pull request” button in the yellow box above the repository
 files.</p>
-<p>Once your changes are reviewed and approved, you will receive an email on how
-to send the final pull request to pandas.</p>
+<p>This will create a pull request, will be reviewed by other developers. It is
+unlikely that a pull request is accepted in its first version, so expect some
+comments on things that can be improved, from more senior pandas contributors.</p>
+<p>For comments in your review, you can make new changes in your local branch for
+that pull request. And once you addressed all the comments, you can commit them
+and push again to your local branch. As you used the parameter <cite>-u</cite> in your
+first push, you can simply run:</p>
+<blockquote>
+<div><div class="line-block">
+<div class="line"><code class="docutils literal"><span class="pre">git</span> <span class="pre">push</span></code></div>
+</div>
+</div></blockquote>
+<p>from your local branch, and the changes will be pushed to your remote branch.</p>
+<p>Updating your remote branch automatically updates the pull request, so you do
+not need to create a new pull request, or make any other changes in the one
+already created.</p>
+<p>If you want to add any clarification to your changes, or you think the reviewer
+misunderstood something, you can add a comment to the pull request.</p>
+<p>Do not feel discouraged by having more than one review requesting changes for
+the same pull request. While in the first contributions is normal to feel
+frustrated for getting feedback requesting changes, it is actually because of
+reviews that the open source software quality is very high. And also, it is
+probably the part of contributing to open source projects in which you will
+learn more. So, be patient and enjoy. And feel free to provide constructive
+feedback in other contributors pull requests too.</p>
 </div>
 </div>
 
@@ -143,7 +178,7 @@ <h3><a href="contents.html">Table Of Contents</a></h3>
 <li><a class="reference internal" href="#visual-validation-of-the-docstring">2. Visual validation of the docstring</a></li>
 <li><a class="reference internal" href="#validate-that-the-docstring-is-clear-to-others">3. Validate that the docstring is clear to others</a></li>
 <li><a class="reference internal" href="#commit-your-changes">4. Commit your changes</a></li>
-<li><a class="reference internal" href="#push-your-changes-to-the-sprint-repository">5. Push your changes to the sprint repository</a></li>
+<li><a class="reference internal" href="#push-your-changes-to-pandas">5. Push your changes to pandas</a></li>
 </ul>
 </li>
 </ul>