New changes should go into pr/ folder #4070
Conversation
since these are empty files, the eventual tools/ script that will concatenate these into development.txt can use these as a test case
docs/source/whatsnew/pr/README.md
Outdated
There was a problem hiding this comment.
"filename starting with incompat-, e.g. incompat-switching-to-perl.rst.
There was a problem hiding this comment.
Thomas Kluyver, on 2013-08-19 17:14, wrote:
"filename starting with
incompat-, e.g.incompat-switching-to-perl.rst.
ah yes, I had intended to write it that way as I started that
sentence, but never carried that sentiment through. Fixed now,
thanks, Thomas
docs/source/whatsnew/pr/README.md
Outdated
There was a problem hiding this comment.
I'd change "should have" to must have in boldface, so it's clear that this is a requirement and not a suggestion.
|
Other than my minor suggestion, looks good, thanks! Since this is a bit of a workflow change and nothing that needs to be rushed, let's let it simmer for a few days so others have a chance to provide feedback on the whole idea. Needless to say, I'm +1. |
|
ok, sounds good, added the must have wording |
|
+1 from me as well.
|
There was a problem hiding this comment.
Why not use a prefix for both features and incompat to be consistent?
There was a problem hiding this comment.
Wouldn't it be convenient to have these sorted in time? Perhaps prefix with the merge date or the PR number?
There was a problem hiding this comment.
The script will look at the modified date to put them in reverse chronological order. I'd like to avoid making a complex naming scheme for the snippet files: let's keep it simple so we get more people doing it.
There was a problem hiding this comment.
I was thinking more of someone browsing the files in the repo, rather than having to parse it with a script first.
There was a problem hiding this comment.
Our intention is that these files are just a temporary thing, and they're automatically put into the real what's new doc every few days, and certainly before the release. We're just frustrated by all our pull requests conflicting with one another.
There was a problem hiding this comment.
I think that each entry should also have a link to the underlying PR on
GitHub using the #2345 notation everyone is familiar with.
On Tue, Aug 20, 2013 at 3:09 PM, Thomas Kluyver notifications@github.comwrote:
In 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.rstfile 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
+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 haveOur intention is that these files are just a temporary thing, and they're
automatically put into the real what's new doc every few days, and
certainly before the release. We're just frustrated by all our pull
requests conflicting with one another.—
Reply to this email directly or view it on GitHubhttps://github.com//pull/4070/files#r5882722
.
Brian E. Granger
Cal Poly State University, San Luis Obispo
bgranger@calpoly.edu and ellisonbg@gmail.com
There was a problem hiding this comment.
In Sphinx, the notation is :ghpull:2979``, which gets transformed into a proper link, etc.
There was a problem hiding this comment.
with the only caveat being that one does not know what the PR number is until the Pull Request is made. That # is available after, so would need to either be amended to the commit while the PR is open, or we could grab it from the merge commit, after the fact.
|
A long time ago we had a manually edited What's New, but we got rid of it, in part, because the information was a repetition of commit messages. I am not opposed to this PR, but would like to understand how this is different. |
|
@ellisonbg : this is not a commit-by-commit log of the work, What's New is the document that is the basis for the release announcement. The idea being that we populate that file with content as we go, and then just massage and reorganize it for the release, instead of having to start essentially from nothing just before a release. In 0c81259, Min took what was then in our |
|
Any objections to merging this now so we can start using it? I think everybody has agreed with the basic idea. |
|
I'm taking the lack of objections as assent, and landing this. |
New changes should go into pr/ folder
New changes should go into pr/ folder
6 participants
This PR establishes a new workflow for documents what's new, and backwards
incompatible changes.
It will allow us to avoid extraneous merge conflicts which would otherwise come
from multiple edits to the same part of the developement.rst file directly.
I'll send a note about this to the mailing list shortly, but see
docs/source/whatsnew/pr/REAMDME.md for details