On 07/31/17 18:46, Stefan Seefeld via Boost wrote:

On 31.07.2017 11:06, Marshall Clow via Boost wrote:

...

Get your bug fixes and documentation updates in now!

-- Mashall

Thanks ! Can you please also remind me how / where to submit release notes ?

You can create a PR for this file: https://github.com/boostorg/website/blob/master/feed/history/boost_1_65_0.qb...

El 31/07/2017 a las 19:41, Stefan Seefeld via Boost escribió:

On 31.07.2017 12:52, Andrey Semashev via Boost wrote:

...

On 07/31/17 18:46, Stefan Seefeld via Boost wrote:

...

Thanks ! Can you please also remind me how / where to submit release notes ? You can create a PR for this file:

https://github.com/boostorg/website/blob/master/feed/history/boost_1_65_0.qb... Thanks, will do.

[I think it would be much simpler for everyone involved if each project kept its own release notes (perhaps in the `meta/` subdirectory ?)

+1. Of course that means someone has to volunteer to do the integration script from meta/release_notes.json :-/ Joaquín M López Muñoz

On 1 August 2017 at 09:26, Andrey Semashev via Boost wrote:

On 08/01/17 09:31, Joaquin M López Muñoz via Boost wrote:

...

El 31/07/2017 a las 19:41, Stefan Seefeld via Boost escribió:

...

[I think it would be much simpler for everyone involved if each project kept its own release notes (perhaps in the `meta/` subdirectory ?)

+1. Of course that means someone has to volunteer to do the integration script from meta/release_notes.json :-/

I'd rather not use JSON for this as it lacks any means of markup.

It's also quite an error prone format. If there's an error in the metadata I just open a pull request to fix it, but that would too slow for updating release notes, which are often written at the last minute. 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. It wouldn't be clear which module branch to use, master seems the obvious choice, but it couldn't be used when master is frozen. And changes to the release notes after a release could also be confusing. It would also require everyone to write their own release notes. Sometimes people email me if they don't want to write quickbook markup themselves.

Frankly, I'm quite fine with creating PRs for the website. This approach worked well for me for years.

But this is the key point. It's working better than I expected, and better than a lot of the other things.

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.

...

It wouldn't be clear which module branch to use, master seems the obvious choice, but it couldn't be used when master is frozen. And changes to the release notes after a release could also be confusing.

It would also require everyone to write their own release notes.

Yes indeed. So what ? Who is writing them now ?

The answer immediately follows.

...

Sometimes people email me if they don't want to write quickbook markup themselves.

All this sounds like another case of someone being afraid of loosing control. With 100+ libraries being hosted by the Boost organization, I think it's time to come to terms with the idea that there is no way to control them top-down.

Don't be silly, I wrote a lot of the scripts that allow library maintainers to manage things themselves. Why on Earth would I so concerned about controlling the release notes? What's so important about them? I'm getting tired of people casting aspersions on anyone who disagrees with them.

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. Stefan -- ...ich hab' noch einen Koffer in Berlin...

On 01.08.2017 17:09, Raffi Enficiaud via Boost wrote:

Le 01.08.17 à 22:18, Stefan Seefeld via Boost a écrit :

...

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.

Is this really the case, and is Boost enforcing this? I believe not:

* feel free to not publish release notes that would be visible on boost.org * feel free to publish whatever documentation and release notes to whatever server of your own

Fair enough. All that is missing for Boost's central documentation (release notes: http://www.boost.org/users/history/version_1_64_0.html, library listing: http://www.boost.org/doc/libs/, bug reporting: http://www.boost.org/development/bugs.html, etc.) is to point to individual projects, such that all that info gets pulled from where it should be.

Please allow me to give you an excerpt from a post of yours, not so long ago (20.05.16, 17:45):

""" It is absurd how much ink is wasted on completely meaningless questions such as where build system artifacts should be placed, as those have absolutely no impact on end-users. """

Touché. However, this isn't so much about technical details than it is about the organizational structure of the whole thing.

I would be glad if we can stay in-topic.

Cheers, Raffi

PS: I am also *very* glad that the release process is moving on, despite the recent chaos on the list and organization. I also want to add that the "people" (which certainly can be counted on my single hand) that are structuring Boost with their tools, servers, infrastructure in general are doing a wonderful job.

I'm *very* grateful for all the help and assistance from others to keep Boost running, so please do not read my criticism (or in fact feature requests) as criticism of anyone's hard work. Stefan -- ...ich hab' noch einen Koffer in Berlin...

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 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 -- ...ich hab' noch einen Koffer in Berlin...

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

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

On 02.08.2017 04:41, Andrey Semashev via Boost wrote:

On 08/02/17 04:17, Stefan Seefeld via Boost wrote:

...

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

1. How would release-specific release notes be maintained in this setup? E.g. when you need to update release notes after a shipped release.

That's up to the project maintainers. (This and similar problems has been solved so many times that I don't think we need to consider it here, in particular when the focus is on de-centralization.)

2. How would the users see the summary release notes for a Boost release on one page? Having a list of links to library-specific release notes is not good enough.

I don't agree with your "not good enough" assessment. While it's of course possible to tie individual release notes back into the main website, this would increase coupling, and thus would augment the complexity and maintenance burden.

And personally, I don't like gh-pages approach because it means storing auto-generated content in git, even if in a separate branch.

That's a separate discussion, which (surprise !) I'd prefer to have per project. Stefan -- ...ich hab' noch einen Koffer in Berlin...

Le 01.08.17 à 10:26, Andrey Semashev via Boost a écrit :

On 08/01/17 09:31, Joaquin M López Muñoz via Boost wrote:

...

El 31/07/2017 a las 19:41, Stefan Seefeld via Boost escribió:

...

On 31.07.2017 12:52, Andrey Semashev via Boost wrote:

...

On 07/31/17 18:46, Stefan Seefeld via Boost wrote:

...

Thanks ! Can you please also remind me how / where to submit release notes ? You can create a PR for this file:

https://github.com/boostorg/website/blob/master/feed/history/boost_1_65_0.qb...

Thanks, will do.

[I think it would be much simpler for everyone involved if each project kept its own release notes (perhaps in the `meta/` subdirectory ?)

+1. Of course that means someone has to volunteer to do the integration script from meta/release_notes.json :-/

I'd rather not use JSON for this as it lacks any means of markup.

Frankly, I'm quite fine with creating PRs for the website. This approach worked well for me for years.

Me too, it is dead simple and well integrated with the rest of the doc for referencing documentation entries directly from there. Raffi