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

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 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/<project>", 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/<project>" 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