[release notes] Linking to github issues/pull requests
Hi, I've added templates for linking to github issues and pull requests from the release notes. There are two templates: [github module number] which expands to '#number' [github_pr module number] which expands to 'PR#number'. Both will be linked, they need the name of the module to link to the right place. We only really need the issue template as github redirects to the pull request if appropriate, but existing release notes have been using the PR#3 format, so I thought it should support that. You can see an example in the unordered release notes for 1.67.0: https://github.com/boostorg/website/blob/master/feed/history/boost_1_67_0.qb... http://www.boost.org/users/history/in_progress.html Does that look okay? Daniel
On 12.01.2018 06:36, Daniel James via Boost wrote:
Hi,
I've added templates for linking to github issues and pull requests from the release notes. There are two templates:
[github module number] which expands to '#number' [github_pr module number] which expands to 'PR#number'.
Both will be linked, they need the name of the module to link to the right place.
We only really need the issue template as github redirects to the pull request if appropriate, but existing release notes have been using the PR#3 format, so I thought it should support that.
You can see an example in the unordered release notes for 1.67.0:
https://github.com/boostorg/website/blob/master/feed/history/boost_1_67_0.qb... http://www.boost.org/users/history/in_progress.html
Does that look okay?
Anything that increases the coupling between boost projects worries me. I think this proposal would work much better if it was used to generate per-project release notes. Nothing speaks against linking to per-project release-notes from a single boost release document. but the logic to syndicate that information shouldn't lead to more coupling. Stefan -- ...ich hab' noch einen Koffer in Berlin...
On 01/12/18 15:23, Stefan Seefeld via Boost wrote:
On 12.01.2018 06:36, Daniel James via Boost wrote:
Hi,
I've added templates for linking to github issues and pull requests from the release notes. There are two templates:
[github module number] which expands to '#number' [github_pr module number] which expands to 'PR#number'.
Both will be linked, they need the name of the module to link to the right place.
We only really need the issue template as github redirects to the pull request if appropriate, but existing release notes have been using the PR#3 format, so I thought it should support that.
You can see an example in the unordered release notes for 1.67.0:
https://github.com/boostorg/website/blob/master/feed/history/boost_1_67_0.qb... http://www.boost.org/users/history/in_progress.html
Does that look okay?
Anything that increases the coupling between boost projects worries me. I think this proposal would work much better if it was used to generate per-project release notes. Nothing speaks against linking to per-project release-notes from a single boost release document. but the logic to syndicate that information shouldn't lead to more coupling.
Just providing links to project-specific release notes is not enough, IMO. I would prefer aggregated release notes to be readable in one place, even if they are collected from project-specific sources. Although I don't see much problem with the current setup as well. In any case, that is a completely different piece of work from what Daniel have done.
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Daniel James via Boost Sent: 12 January 2018 11:36 To: boost@lists.boost.org Cc: Daniel James Subject: [boost] [release notes] Linking to github issues/pull requests
Hi,
I've added templates for linking to github issues and pull requests from the release notes. There are two templates:
[github module number] which expands to '#number' [github_pr module number] which expands to 'PR#number'.
Both will be linked, they need the name of the module to link to the right place.
We only really need the issue template as github redirects to the pull request if appropriate, but existing release notes have been using the PR#3 format, so I thought it should support that.
You can see an example in the unordered release notes for 1.67.0:
https://github.com/boostorg/website/blob/master/feed/history/boost_1_67_0.qb... http://www.boost.org/users/history/in_progress.html
Does that look okay?
Perfect :-) Thanks Paul PS Just needs adding [github module number] which expands to '#number' [github_pr module number] which expands to 'PR#number'. and an example like the above to the Quickbook docs ;-) And get people to use it too (the difficult bit!). --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
On 01/12/18 15:28, Paul A. Bristow via Boost wrote:
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Daniel James via Boost Sent: 12 January 2018 11:36 To: boost@lists.boost.org Cc: Daniel James Subject: [boost] [release notes] Linking to github issues/pull requests
Hi,
I've added templates for linking to github issues and pull requests from the release notes. There are two templates:
[github module number] which expands to '#number' [github_pr module number] which expands to 'PR#number'.
Both will be linked, they need the name of the module to link to the right place.
We only really need the issue template as github redirects to the pull request if appropriate, but existing release notes have been using the PR#3 format, so I thought it should support that.
You can see an example in the unordered release notes for 1.67.0:
https://github.com/boostorg/website/blob/master/feed/history/boost_1_67_0.qb... http://www.boost.org/users/history/in_progress.html
Does that look okay?
Perfect :-)
Thanks
Paul
PS Just needs adding
[github module number] which expands to '#number' [github_pr module number] which expands to 'PR#number'.
and an example like the above
to the Quickbook docs ;-)
And get people to use it too (the difficult bit!).
As far as I understand, this is not a builtin Quickbook feature. Those templates (and [ticket number] as well) are defined by the release notes infrastructure.
On 12.01.2018 07:32, Andrey Semashev via Boost wrote:
On 01/12/18 15:28, Paul A. Bristow via Boost wrote:
PS Just needs adding
[github module number] which expands to '#number' [github_pr module number] which expands to 'PR#number'.
and an example like the above
to the Quickbook docs ;-)
And get people to use it too (the difficult bit!).
As far as I understand, this is not a builtin Quickbook feature. Those templates (and [ticket number] as well) are defined by the release notes infrastructure.
What's the state of this new feature ? What do I need to do to use it in my own documentation ? (I have no idea what boost's "release notes infrastructure" is. Where can I read about it ?) Thanks, Stefan -- ...ich hab' noch einen Koffer in Berlin...
On 14 February 2018 at 01:36, Stefan Seefeld via Boost <boost@lists.boost.org> wrote:
What's the state of this new feature ? What do I need to do to use it in my own documentation ? (I have no idea what boost's "release notes infrastructure" is. Where can I read about it ?)
They're just quickbook templates defined for the release notes, you can do the same in your own documentation. You can see the definitions at: https://github.com/boostorg/website/blob/712117cf664d99efe76539fa180a44c7bac... They use escaped docbook because older versions of quickbook didn't support template parameters in links. Quickbook 1.7 does (you're using it if you have a [quickbook 1.7] tag at the start of your file), so they're easier to define there, I've attached an example.
On 14.02.2018 03:57, Daniel James via Boost wrote:
On 14 February 2018 at 01:36, Stefan Seefeld via Boost <boost@lists.boost.org> wrote:
What's the state of this new feature ? What do I need to do to use it in my own documentation ? (I have no idea what boost's "release notes infrastructure" is. Where can I read about it ?) They're just quickbook templates defined for the release notes, you can do the same in your own documentation. You can see the definitions at:
https://github.com/boostorg/website/blob/712117cf664d99efe76539fa180a44c7bac...
They use escaped docbook because older versions of quickbook didn't support template parameters in links. Quickbook 1.7 does (you're using it if you have a [quickbook 1.7] tag at the start of your file), so they're easier to define there, I've attached an example.
I see these templates are defined in `website/feed/ext.qbk`. How or when is that source being pulled into the documentation ? (That's presumably what you are referring to as "release notes infrastructure" ?) As I mentioned in a prior reply in this thread, I'd really like to be able to use such features in my projects' own documentation, i.e. as part of a regular documentation build, which has no notion of the above `website` code. But that would only work if such templates would become part of `quickbook` itself, rather than being integrated into a separate boost module such as `website`. (Of course, in this particular case the templates are so simple I can just clone them into my own doc infrastructure.) Thanks, Stefan -- ...ich hab' noch einen Koffer in Berlin...
On 14 February 2018 at 12:15, Stefan Seefeld via Boost <boost@lists.boost.org> wrote:
I see these templates are defined in `website/feed/ext.qbk`. How or when is that source being pulled into the documentation ? (That's presumably what you are referring to as "release notes infrastructure" ?)
There's an '[import ext.qbk]' at the top of the release notes, which imports all the templates and macros. When building the release notes quickbook is called with the appropriate include path (i.e. something like 'quickbook feed/history/boost_1_66_0.qbk -I feed/'). You can add an include path in Boost Build using '<include>': path-constant include_path : path-to-include-dir ; xml target : source.qbk : <include>$(include_path) ;
As I mentioned in a prior reply in this thread, I'd really like to be able to use such features in my projects' own documentation, i.e. as part of a regular documentation build, which has no notion of the above `website` code. But that would only work if such templates would become part of `quickbook` itself, rather than being integrated into a separate boost module such as `website`.
I wouldn't want to make something so specific part of the language. We could make a template library available somewhere though.
On 14.02.2018 07:48, Daniel James via Boost wrote:
I see these templates are defined in `website/feed/ext.qbk`. How or when is that source being pulled into the documentation ? (That's presumably what you are referring to as "release notes infrastructure" ?) There's an '[import ext.qbk]' at the top of the release notes, which imports all the templates and macros. When building the release notes quickbook is called with the appropriate include path (i.e. something
On 14 February 2018 at 12:15, Stefan Seefeld via Boost <boost@lists.boost.org> wrote: like 'quickbook feed/history/boost_1_66_0.qbk -I feed/').
You can add an include path in Boost Build using '<include>':
path-constant include_path : path-to-include-dir ;
xml target : source.qbk : <include>$(include_path) ;
Thanks !
As I mentioned in a prior reply in this thread, I'd really like to be able to use such features in my projects' own documentation, i.e. as part of a regular documentation build, which has no notion of the above `website` code. But that would only work if such templates would become part of `quickbook` itself, rather than being integrated into a separate boost module such as `website`. I wouldn't want to make something so specific part of the language. We could make a template library available somewhere though.
Exactly, that's what I had in mind: some "runtime" that's part of the documentation module itself, rather than "website" or other mostly independent downstream project. Regards, Stefan -- ...ich hab' noch einen Koffer in Berlin...
On 14 February 2018 at 12:51, Stefan Seefeld via Boost <boost@lists.boost.org> wrote:
Exactly, that's what I had in mind: some "runtime" that's part of the documentation module itself, rather than "website" or other mostly independent downstream project.
I'd probably put it somewhere in the 'doc' directory of the super project, as that's where the shared css and image files are.
On 14.02.2018 08:08, Daniel James via Boost wrote:
Exactly, that's what I had in mind: some "runtime" that's part of the documentation module itself, rather than "website" or other mostly independent downstream project. I'd probably put it somewhere in the 'doc' directory of the super
On 14 February 2018 at 12:51, Stefan Seefeld via Boost <boost@lists.boost.org> wrote: project, as that's where the shared css and image files are.
That would be suboptimal, as it would increase the coupling of individual projects to the super project. (I have actually cloned the shared resources you mention into Boost.Python precisely so I can build it stand-alone, with only dependencies to individual modules (or boost system packages in my Fedora environment), rather than a full boost repo checkout.) Stefan -- ...ich hab' noch einen Koffer in Berlin...
On 14 February 2018 at 13:42, Stefan Seefeld via Boost <boost@lists.boost.org> wrote:
That would be suboptimal, as it would increase the coupling of individual projects to the super project. (I have actually cloned the shared resources you mention into Boost.Python precisely so I can build it stand-alone, with only dependencies to individual modules (or boost system packages in my Fedora environment), rather than a full boost repo checkout.)
But you'd still be coupled with whatever module the files are in. I also wouldn't know how to set up boost build for such an environment.
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Daniel James via Boost Sent: 14 February 2018 13:08 To: boost@lists.boost.org Cc: Daniel James Subject: Re: [boost] [release notes] Linking to github issues/pull requests
On 14 February 2018 at 12:51, Stefan Seefeld via Boost <boost@lists.boost.org> wrote:
Exactly, that's what I had in mind: some "runtime" that's part of the documentation module itself, rather than "website" or other mostly independent downstream project.
I'd probably put it somewhere in the 'doc' directory of the super project, as that's where the shared css and image files are.
Quickbookers might also find useful a collection of templates used in the Boost.Math library docs. I have called it html4_symbols but another name might be less version specific, like html_symbols.qbk? [template Alpha[]'''Α'''] [/ ? Greek capital letter alpha] ... [template alpha[]'''α'''] [/ a Greek small letter alpha] lots of squiggles and mathy thingys using Unicode to make them more readable in the code [template radic[]'''√'''] [/ v square root = radical sign] [template prop[]'''∝'''] [/ ? proportional to] [template infin[]'''∞'''] [/ 8 infinity] [template bull[]'''•'''] [/ . bullet = black small circle] [template frac14[]'''¼'''] [/ fraction quarter] [template diams[]'''♦'''] [/ ? black diamond suit] [template euro[]'''€'''] [/ ? Euro currency symbol] The location you suggest would be a logical place to put it? Paul PS Stefan can *copy* these to make his project standalone and yet reuse other(s) templates? --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
On 01/12/18 14:36, Daniel James via Boost wrote:
Hi,
I've added templates for linking to github issues and pull requests from the release notes. There are two templates:
[github module number] which expands to '#number' [github_pr module number] which expands to 'PR#number'.
Both will be linked, they need the name of the module to link to the right place.
We only really need the issue template as github redirects to the pull request if appropriate, but existing release notes have been using the PR#3 format, so I thought it should support that.
You can see an example in the unordered release notes for 1.67.0:
https://github.com/boostorg/website/blob/master/feed/history/boost_1_67_0.qb... http://www.boost.org/users/history/in_progress.html
Does that look okay?
Looks good, although I would prefer if Trac tickects could be distinguished from GitHub issues. Maybe expand issues to GH#number? Thanks for the enhancement, anyway. :)
On 12 January 2018 at 12:35, Andrey Semashev via Boost <boost@lists.boost.org> wrote:
Looks good, although I would prefer if Trac tickects could be distinguished from GitHub issues. Maybe expand issues to GH#number?
I don't think GH would be as obvious as PR. Maybe GitHub#number would be better? I was following the existing release notes were people have just used #number. It's not that confusing as the numbers are much lower than they are for trac, and the links go to the right place.
On 01/13/18 19:43, Daniel James via Boost wrote:
On 12 January 2018 at 12:35, Andrey Semashev via Boost <boost@lists.boost.org> wrote:
Looks good, although I would prefer if Trac tickects could be distinguished from GitHub issues. Maybe expand issues to GH#number?
I don't think GH would be as obvious as PR. Maybe GitHub#number would be better?
GitHub#number is ok, too. I wanted the prefix to be short, if possible, so that the issue numbers don't clutter the rest of the text too much, especially if there are many references.
I was following the existing release notes were people have just used #number. It's not that confusing as the numbers are much lower than they are for trac, and the links go to the right place.
Yeah, it's not a strong preference of mine, as I can always see where the link leads to. Just something that I would do in my release notes. It's fine if you decide to leave it without a prefix.
On Fri, Jan 12, 2018 at 3:36 AM, Daniel James via Boost <boost@lists.boost.org> wrote:
I've added templates for linking to github issues and pull requests from the release notes. There are two templates:
Thank you, this will be very helpful for Beast as I rely heavily on GitHub to interact with users, and the upcoming release notes for Beast will be massive. Regards
participants (5)
-
Andrey Semashev -
Daniel James -
Paul A. Bristow -
Stefan Seefeld -
Vinnie Falco