Re: [boost] Reminder: Boost Master branch will close for the 1.65.0 release on Wednesday

Subject: Re: [boost] Reminder: Boost Master branch will close for the 1.65.0 release on Wednesday
From: Stefan Seefeld (stefan_at_[hidden])
Date: 2017-08-02 03:47:16

On 01.08.2017 23:40, Edward Diener via Boost wrote:
> On 8/1/2017 9:17 PM, Stefan Seefeld via Boost wrote:
>> On 01.08.2017 19:20, Edward Diener via Boost wrote:
>>> On 8/1/2017 4:18 PM, Stefan Seefeld via Boost wrote:
>>>> On 01.08.2017 15:21, Andrey Semashev via Boost wrote:
>>>>> On 08/01/17 22:14, Daniel James via Boost wrote:
>>>>>> On 1 August 2017 at 19:27, Stefan Seefeld via Boost
>>>>>> <boost_at_[hidden]> wrote:
>>>>>>> On 01.08.2017 05:12, Daniel James via Boost wrote:
>>>>>>>> I can see other problems with a more distributed approach. We'd
>>>>>>>> lose
>>>>>>>> the ability to edit release notes, which we do on occasion, and
>>>>>>>> pull
>>>>>>>> requests also make it easier to track changes as someone has to
>>>>>>>> approve them.
>>>>>>>
>>>>>>> Why would anyone want to edit or even just approve release notes I
>>>>>>> wrote
>>>>>>> about a project I maintain ?
>>>>>>
>>>>>> Fix links, typos, markup etc. A lot of that is done by Akira
>>>>>> Takahashi.
>>>>>
>>>>> Multiple times we also had to add to release notes after the release
>>>>> has been shipped. For example, add notes about critical problems and
>>>>> links to patches.
>>>>
>>>> Yes, all of which can be done per project, if Boost would allow
>>>> release
>>>> notes to be stored in the project-specific repositories, and rendered
>>>> from project-specific documentation, rather than all from a single
>>>> monolithic place.
>>>
>>> I agree with you that having some method for individual
>>> libraries/tools to create their own release notes would be better than
>>> having a central place where release notes are kept. But how would
>>> this be done and who is going to do it ? If you were willing to
>>> propose a way for this to be done and then write some code ( maybe
>>> Python ) to combine the release notes for the individual
>>> libraries/tools into the final release notes format for any given
>>> release, then your argument would have much more traction. Also I
>>> suspect that the individual library/tool format for release notes
>>> should allow for ongoing notes for each release rather than a complete
>>> replacement of a previous release's release notes with a new set of
>>> notes.
>>
>> You are right, of course. And I did indeed propose a solution in private
>> conversation, a few months ago. It goes somewhat like this:
>>
>> 1) Write a template "index.html" to be used as the "landing page" for
>> all (individual) projects, containing all the essential information,
>> from pointers to docs, issue tracker, github repo, wiki, etc.
>> 2) "Instantiate this template (by filling in some placeholders such as
>> library name, etc., from the respective "meta/libraries.json" file) and
>> add it to the "gh-pages" branches of all repos that don't yet have an
>> "index.html" file.
>> 3) Change the html in the "website" repo to refer to those URLs (served
>> as "http://boostorg.github.io/
>", rather than

>> "http://boost.org") after validating that all the referenced end-points
>> exist
>> 4) Allow project maintainers to replace (customize) their "index.html"
>> to refer to documentation (etc.) they manage "locally", i.e. generate on
>> "http://boostorg.github.io/
>"

>> 5) At the same time, remove the corresponding (now obsoleted) content
>> from boost.org
>
> Your items above are way too complicated for just creating individual
> library/tool release notes,

...because this addresses more than just the centralized release notes
issue.

> besides which many libraries do not write docs in HTML at all.

So what ? All I'm proposing is to inject an indirection that allows
those maintainers who wish to customize the process to do so. For those
who don't, all of this will be fully transparent.

> My suggestion is that you scale down your implementation to something
> which provides just release notes for each release, and which could be
> picked up to create centralized release notes for a release.
I don't see what problem this would solve.
> My suggestion is also that the release notes be plain text.

(I agree, but this is a tangential issue.)

        Stefan

-- 
      ...ich hab' noch einen Koffer in Berlin...