From e17741fe1e5e044ba66db4f12152eac4b9b5616b 2013-08-27 18:07:18
From: Thomas Kluyver <takowl@gmail.com>
Date: 2013-08-27 18:07:18
Subject: [PATCH] Merge pull request #4070 from ivanov/doc-pr-folder

New changes should go into pr/ folder
---

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 328b2d5..478a722 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -28,6 +28,9 @@ 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),
diff --git a/docs/source/whatsnew/development.rst b/docs/source/whatsnew/development.rst
index 575807c..21239df 100644
--- a/docs/source/whatsnew/development.rst
+++ b/docs/source/whatsnew/development.rst
@@ -4,6 +4,13 @@
 
 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
 
diff --git a/docs/source/whatsnew/pr/README.md b/docs/source/whatsnew/pr/README.md
new file mode 100644
index 0000000..b098249
--- /dev/null
+++ b/docs/source/whatsnew/pr/README.md
@@ -0,0 +1,18 @@
+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.
diff --git a/docs/source/whatsnew/pr/antigravity-feature.rst b/docs/source/whatsnew/pr/antigravity-feature.rst
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/docs/source/whatsnew/pr/antigravity-feature.rst
diff --git a/docs/source/whatsnew/pr/incompat-switching-to-perl.rst b/docs/source/whatsnew/pr/incompat-switching-to-perl.rst
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/docs/source/whatsnew/pr/incompat-switching-to-perl.rst