[release notes] Linking to github issues/pull requests

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
18 messages Options
Reply | Threaded
Open this post in threaded view
|

[release notes] Linking to github issues/pull requests

Boost - Dev mailing list
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.qbk
http://www.boost.org/users/history/in_progress.html

Does that look okay?

Daniel

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [release notes] Linking to github issues/pull requests

Boost - Dev mailing list
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.qbk
> 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...
   


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [release notes] Linking to github issues/pull requests

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list


> -----Original Message-----
> From: Boost [mailto:[hidden email]] On Behalf Of Daniel James via Boost
> Sent: 12 January 2018 11:36
> To: [hidden email]
> 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.qbk
> 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






_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [release notes] Linking to github issues/pull requests

Boost - Dev mailing list
On 01/12/18 15:28, Paul A. Bristow via Boost wrote:

>
>
>> -----Original Message-----
>> From: Boost [mailto:[hidden email]] On Behalf Of Daniel James via Boost
>> Sent: 12 January 2018 11:36
>> To: [hidden email]
>> 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.qbk
>> 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.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [release notes] Linking to github issues/pull requests

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
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.qbk
> 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. :)

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [release notes] Linking to github issues/pull requests

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
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.qbk
>> 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.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [release notes] Linking to github issues/pull requests

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 12 January 2018 at 12:35, Andrey Semashev via Boost
<[hidden email]> 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.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [release notes] Linking to github issues/pull requests

Boost - Dev mailing list
On 01/13/18 19:43, Daniel James via Boost wrote:
> On 12 January 2018 at 12:35, Andrey Semashev via Boost
> <[hidden email]> 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.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [release notes] Linking to github issues/pull requests

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On Fri, Jan 12, 2018 at 3:36 AM, Daniel James via Boost
<[hidden email]> 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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [release notes] Linking to github issues/pull requests

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
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...
   


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [release notes] Linking to github issues/pull requests

Boost - Dev mailing list
On 14 February 2018 at 01:36, Stefan Seefeld via Boost
<[hidden email]> 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/712117cf664d99efe76539fa180a44c7bacd78ef/feed/ext.qbk#L48

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.


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

ticket-1.7.qbk (738 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [release notes] Linking to github issues/pull requests

Boost - Dev mailing list
On 14.02.2018 03:57, Daniel James via Boost wrote:

> On 14 February 2018 at 01:36, Stefan Seefeld via Boost
> <[hidden email]> 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/712117cf664d99efe76539fa180a44c7bacd78ef/feed/ext.qbk#L48
>
> 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...
   


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [release notes] Linking to github issues/pull requests

Boost - Dev mailing list
On 14 February 2018 at 12:15, Stefan Seefeld via Boost
<[hidden email]> 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.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [release notes] Linking to github issues/pull requests

Boost - Dev mailing list
On 14.02.2018 07:48, Daniel James via Boost wrote:

> On 14 February 2018 at 12:15, Stefan Seefeld via Boost
> <[hidden email]> 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) ;

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...
   


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [release notes] Linking to github issues/pull requests

Boost - Dev mailing list
On 14 February 2018 at 12:51, Stefan Seefeld via Boost
<[hidden email]> 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.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [release notes] Linking to github issues/pull requests

Boost - Dev mailing list
On 14.02.2018 08:08, Daniel James via Boost wrote:
> On 14 February 2018 at 12:51, Stefan Seefeld via Boost
> <[hidden email]> 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.

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...
   


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [release notes] Linking to github issues/pull requests

Boost - Dev mailing list
On 14 February 2018 at 13:42, Stefan Seefeld via Boost
<[hidden email]> 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.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [release notes] Linking to github issues/pull requests

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
> -----Original Message-----

> From: Boost [mailto:[hidden email]] On Behalf Of Daniel James via Boost
> Sent: 14 February 2018 13:08
> To: [hidden email]
> 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
> <[hidden email]> 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[]'''&#x391;'''] [/ ? Greek capital letter alpha]
...
[template alpha[]'''&#x3B1;'''] [/ a Greek small letter alpha]

lots of squiggles and mathy thingys using Unicode to make them more readable in the code

[template radic[]'''&#x221A;'''] [/  v square root = radical sign]
[template prop[]'''&#x221D;'''] [/  ? proportional to]
[template infin[]'''&#x221E;'''] [/  8 infinity]
[template bull[]'''&#x2022;'''] [/  . bullet = black small circle]
[template frac14[]'''&#x00BC;'''] [/ fraction quarter]
[template diams[]'''&#x2666;'''] [/  ? black diamond suit]
[template euro[]'''&#x20AC;'''] [/  ? 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




_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

html4_symbols.qbk (13K) Download Attachment