Add documentation on updating references in NEWS.md #14162
Conversation
| @@ -108,6 +108,8 @@ It is encouraged to write all new docstrings in Markdown markup. If you need to | |||
| Many of the existing docstrings are currently restructured text codeblocks and these will be transitioned to Markdown over time. RST codeblocks are delineated with the triple-quote (\`\`\`rst \`\`\`) Makdown codeblock syntax. | |||
| The content of the codeblock is spliced directly into the final restructured text document unmodified. | |||
|
|
|||
| If you decide to add some news to `NEWS.md` and you include a reference to a pull request or issue you should make sure to run `julia doc/NEWS-update.jl` from Julia's root directory before you submit. Running this ensures that the cross-reference links are up-to-date. | |||
There was a problem hiding this comment.
more accurately ./julia on unix, or usr/bin/julia to be cross platform
There was a problem hiding this comment.
Need a comma before "you should make". In general, maybe be a bit more explicit:
For new functionality and other substantial changes, add a brief summary to `NEWS.md`. The news item should cross reference the pull request (PR) parenthetically, in the form `([#pr])`; after adding this, run `julia doc/NEWS-update.jl` from the `julia` directory to update the cross-reference links. (Submit the PR, find out the PR number, and then push an additional commit updating `NEWS.md` to the PR.)
There was a problem hiding this comment.
(Any recent version of Julia should work for the update-NEWS.jl script, so I don't think we need to be too specific about that.)
There was a problem hiding this comment.
@stevengj I preferred most of your wording over mine. I did some work on the last sentence though. I ended up going with ./julia since it is more accurate and not overly verbose.
There was a problem hiding this comment.
Shouldn't you delete the old wording then? It looks like you have both paragraphs in the PR.
|
Added the commas. You are a much better editor than I. |
|
Note that you'll need to squash the commits ( Also, be sure to add a NEWS item for this change. (Just kidding.) |
|
Commits have been squashed. I forgot to delete my original paragraph which I have now corrected. |
Add documentation on updating references in NEWS.md
Thanks @stevengj and @tkelman for bringing this up in #14114.