Merge pull request #4070 from ivanov/doc-pr-folder

New changes should go into pr/ folder

docs/source/whatsnew/pr/README.md

@@ -0,0 +1,18 b''
+Documenting What's New
+----------------------
+
+When making a new pull request that either adds a new feature, or makes a
+backwards-incompatible change to IPython, please add a new `.rst` file in this
+directory documenting this change as a part of your Pull Request.
+
+This will allow multiple Pull Requests to do the same without conflicting with
+one another. Periodically, IPython developers with commit rights will run a
+script and populate [development.rst](../development.rst)
+with the contents of this directory, and clean it up.
+
+Files which describe new features can have any name, such as
+`antigravity-feature.rst`, whereas backwards incompatible changes **must have**
+have a filename starting with `incompat-`, such as
+`incompat-switching-to-perl.rst`.  Our "What's new" files always have two
+sections,  and this prefix scheme will make sure that the backwards incompatible
+changes get routed to their proper section.

CONTRIBUTING.md

@@ -28,6 +28,9 b' Some guidelines on contributing to IPython:'
 * Pull Requests should be tested, if feasible:
     - bugfixes should include regression tests
     - new behavior should at least get minimal exercise
+* New features and backwards-incompatible changes should be documented by adding
+  a new file to the [pr](docs/source/whatsnew/pr) directory, see [the README.md
+  there](docs/source/whatsnew/pr/README.md) for details.
 
 [Travis](http://travis-ci.org/#!/ipython/ipython) does a pretty good job testing IPython and Pull Requests,
 but it may make sense to manually perform tests (possibly with our `test_pr` script),

docs/source/whatsnew/development.rst

@@ -4,6 +4,13 b''
 
 This document describes in-flight development work.
 
+.. warning::
+
+    Please do not edit this file by hand (doing so will likely cause merge
+    conflicts for other Pull Requests). Instead, create a new file in the
+    `docs/source/whatsnew/pr` folder
+
+
 - `%%capture` cell magic now captures the rich display output, not just
   stdout/stderr