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: Edward Diener (eldiener_at_[hidden])
Date: 2017-08-02 03:40:00

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, besides which many libraries do not write 
docs in HTML at all. 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. My suggestion is also that the release notes be 
plain text.

> 
> Voila, at that point all the responsibility for content goes to
> individual projects.
> 
> The two essential steps are a) the writing of the index.html template,
> and b) the adding of that file to all (gh-pages branches of) individual
> projects. I'd be happy to help with both.
> 
>          Stefan
>