New Boost Website: Open to Volunteers!

newer
Changes in buildable components...

Vinnie Falco

16 Apr 2022 16 Apr '22

7:18 p.m.

The C++ Alliance is putting together a working prototype of a new website to replace what is currently at boost.org. We could use help with exposition on most of the new pages. And feedback could be helpful to refine some of the interfaces and layouts. If there is consensus and the site replaces boost.org, there will be at least one or more revisions. So it is not necessary to get everything "perfect" on the first pass (or else it will never be finished). Note that this is not a design-by-committee project. There are specific goals that are thought essential to refresh the foundations of Boost's social technology. For example, we are building a forum as the primary means of message-based interaction. However we are also building a connector so that users who want to use a mailing-list style interface can continue to do so with no interruption of service. If you would like to participate in the process of building this site then feel free to subscribe to this new mailing list: https://lists.boost.org/mailman/listinfo.cgi/boost-www Thanks Vinnie

Show replies by date

Stefan Seefeld

16 Apr 16 Apr

7:38 p.m.

Hi all, I'd like to suggest that particular attention be spent on making the new site more modular in its way to syndicate content coming from individual boost projects. In particular, I'm thinking of the current process of submitting project-specific release notes as PRs to the boost website repo. I believe it would be easier for all participants if projects could host their own release notes, and the boost website could then simply link to those. (Of course, this "linking" could take different forms including embedding for convenience.) The same technique could be used for many other pieces of project-specific metadata... Thanks, Stefan -- ...ich hab' noch einen Koffer in Berlin...

Vinnie Falco

8:41 p.m.

On Sat, Apr 16, 2022 at 12:39 PM Stefan Seefeld via Boost wrote:

...

I'd like to suggest...

Well, this is an interesting idea! You should subscribe to the www mailing list... Thanks

Vinnie Falco

8:48 p.m.

On Sat, Apr 16, 2022 at 12:39 PM Stefan Seefeld via Boost wrote:

...

making the new site more modular in its way to syndicate content coming from individual boost projects

We are adding a database, and this kind of feature will be possible in theory. But, in order to ensure that we actually get this thing done we are limiting the scope of new features for the initial release. We aren't touching the documentation and we are striving to make few to no changes in how the release notes are published. What we will have is a repository and a maintenance team which is responsive to opened issues. When this becomes available you should open an issue so it can be discussed and triaged. Given the lack of attention I expect that it will take a couple of years until we are truly happy with a new site; this is more of a marathon rather than a sprint. Thanks

Niall Douglas

9:30 p.m.

On 16/04/2022 21:48, Vinnie Falco via Boost wrote:

...

On Sat, Apr 16, 2022 at 12:39 PM Stefan Seefeld via Boost wrote:

...
making the new site more modular in its way to syndicate content coming from individual boost projects

We are adding a database

I would be opposed to any form of website which relies on a database, unless it is SQLite. I say this from bitter experience. Databases go wrong without maintenance and we've seen on many occasions in the past people happy to volunteer to do stuff for Boost for many years until they quietly disappear, then the thing limps on but becoming ever increasingly erratic and problematic, and then we have to go get people to start ringing other people and then we find said service was being run off some academic server and nobody ever knew about it and then academic people start accusing Boost of network intrusion etc etc. We could just avoid repeating all those past mistakes by not designing in a need for a database. I remind everybody here of my past travails with Boost's pre-github wiki and issue tracker. Let's not repeat that. Where my ideal would be at is a static site generator such as Hugo. Which is like what we've already got, except several generations newer and better technology. It can syndicate content from feeds just fine, you stick it on a five minute cronjob, it's designed to work well doing that. I'm not against databases, so long as it's a SQLite file and said file can get deleted at any time and it doesn't really matter. I used to use one for website visitor counters, as an example. I also think a github repo which acts as the content for the website would be a wise thing to retain. People can raise PRs, they can get approved, content appears on the website. I think that a good pattern to retain rather than yet another portal for reviewing and checking content. Niall

Andrey Semashev

10:22 p.m.

On 4/17/22 00:30, Niall Douglas via Boost wrote:

...

I also think a github repo which acts as the content for the website would be a wise thing to retain. People can raise PRs, they can get approved, content appears on the website. I think that a good pattern to retain rather than yet another portal for reviewing and checking content.

+1. I very much like that the current website can be cloned, with history, and updated locally or online, and then the changes can be merged upstream with PRs. The fact that you're using the usual toolset for this, nothing more than git and your favorite text editor, is a huge plus. Using a separate interface for that, or a database, would be a step in the wrong direction, IMO. Your only database should be git.

Vinnie Falco

10:28 p.m.

On Sat, Apr 16, 2022 at 3:22 PM Andrey Semashev via Boost wrote:

...

+1. I very much like that the current website can be cloned, with history, and updated locally or online, and then the changes can be merged upstream with PRs. The fact that you're using the usual toolset for this, nothing more than git and your favorite text editor, is a huge plus. Using a separate interface for that, or a database, would be a step in the wrong direction, IMO. Your only database should be git.

Yeah static content would stay in the GitHub repository. But dynamic content such as the list of libraries, the list of boost.org accounts corresponding to library maintainers, the tags for libraries, the index for the live news feed on the front page, the forum data, information for user accounts, the results of every review, the review calendar, and so on - those are going into a database. The website we are building is not a static site it is a social media portal for Boost and C++. It cannot be represented merely as a collection of html and css. It is software (i.e. a web application). Django/Python to be precise. I was hoping to have this discussion in the other mailing list, because I didn't want to start a useless discussion here where everyone offers ideas that contradict one another and nothing gets done, which is typically what happens when big line-item things like new websites are discussed. Thanks

Andrey Semashev

10:35 p.m.

On 4/17/22 01:28, Vinnie Falco wrote:

...

On Sat, Apr 16, 2022 at 3:22 PM Andrey Semashev via Boost wrote:

...
+1. I very much like that the current website can be cloned, with history, and updated locally or online, and then the changes can be merged upstream with PRs. The fact that you're using the usual toolset for this, nothing more than git and your favorite text editor, is a huge plus. Using a separate interface for that, or a database, would be a step in the wrong direction, IMO. Your only database should be git.

Yeah static content would stay in the GitHub repository. But dynamic content such as the list of libraries, the list of boost.org accounts corresponding to library maintainers, the tags for libraries, the index for the live news feed on the front page, the forum data, information for user accounts, the results of every review, the review calendar, and so on - those are going into a database.

I don't see why the things you list, perhaps with the exception of the forum content, can't be static content in git. Most of it is already available in git. But I'm not a web developer, so maybe I'm missing something.

Vinnie Falco

10:39 p.m.

On Sat, Apr 16, 2022 at 3:35 PM Andrey Semashev via Boost wrote:

...

I don't see why the things you list, perhaps with the exception of the forum content, can't be static content in git. Most of it is already available in git. But I'm not a web developer, so maybe I'm missing something.

I'm not a web developer either, but I am told from very reputable sources that this is how modern sites do it. Thanks

Niall Douglas

11:30 p.m.

On 16/04/2022 23:28, Vinnie Falco via Boost wrote:

...

On Sat, Apr 16, 2022 at 3:22 PM Andrey Semashev via Boost wrote:

...
+1. I very much like that the current website can be cloned, with history, and updated locally or online, and then the changes can be merged upstream with PRs. The fact that you're using the usual toolset for this, nothing more than git and your favorite text editor, is a huge plus. Using a separate interface for that, or a database, would be a step in the wrong direction, IMO. Your only database should be git.

Yeah static content would stay in the GitHub repository. But dynamic content such as the list of libraries,

Hugo will generate that for you during site build.

...

the list of boost.org accounts corresponding to library maintainers,

Hugo will generate that for you during site build. You can even have it auto replicate the github users for the boostorg account if you want. I have this on the Outcome website, for example - https://ned14.github.io/outcome/credits/

...

the tags for libraries, the index for the live news feed on the front page, the forum data, information for user accounts, the results of every review, the review calendar, and so on - those are going into a database.

Hugo will generate that for you during site build. You don't need a database for any of the above. You don't need user logins either if you let github do that for you. I'm not particularly recommending Hugo, there are alternatives. But I've found it more than plenty powerful enough to do anything you want with a 100% static website. It'll even do comments just fine (staticman.net, it actually does a git commit per comment to your site's github repo).

...

The website we are building is not a static site it is a social media portal for Boost and C++. It cannot be represented merely as a collection of html and css. It is software (i.e. a web application). Django/Python to be precise.

And as soon as you said "web application", you now have me strongly opposed to this entire project. I've deployed those in the past, they require *constant* maintenance, they have a tendency to need ever beefier hardware, things constantly go wrong with them. You might as well just roll out Wordpress, at least it's widely well understood and its maintenance can be outsourced to somebody not us for money.

...

I was hoping to have this discussion in the other mailing list, because I didn't want to start a useless discussion here where everyone offers ideas that contradict one another and nothing gets done, which is typically what happens when big line-item things like new websites are discussed.

I couldn't be bothered refighting this fight. Boost went down this rabbit hole before and it regretted it. I've said my piece. If people want to listen to my advice, good on them. Otherwise you're all digging yourselves a hole you'll regret in years to come as you lock yourselves into a system nobody unpaid will be arsed digging you out of, and as it'll be database based, you'll all be hosed. I'd much rather a Boost subreddit for discussion, let somebody else maintain the database. And if you're going to lock yourself in, better to a major platform with decent SEO and discussion topic search already done for you by others. If we're happy with locking ourselves into github, why not Reddit? Niall

Peter Dimov

9:49 p.m.

Vinnie Falco wrote:

...

We are adding a database, and this kind of feature will be possible in theory. But, in order to ensure that we actually get this thing done we are limiting the scope of new features for the initial release. We aren't touching the documentation and we are striving to make few to no changes in how the release notes are published.

Fixing the way the release notes are published would be pretty useful. We could, e.g. have meta/changelog.json in each library that holds the per-library changes, and generate the release notes from that.

Vinnie Falco

9:53 p.m.

On Sat, Apr 16, 2022 at 2:49 PM Peter Dimov via Boost wrote:

...

We could, e.g. have meta/changelog.json in each library that holds the per-library changes, and generate the release notes from that.

Yes that is possible although it has more to do with the release process (which Sam maintains). Sam? Thanks

Sam Darwin

17 Apr 17 Apr

12:13 a.m.

On the topic of release notes, if the library author prefers to customize and format the text, then being tied precisely to tagged git commit messages could be overly restrictive, but it's a possibility and more automated. Another option, of having a meta/changelog.json file, is an idea. It would be important to require the formatting of that file to include the release version, every time, so earlier notes don't automatically get pulled into later releases. The processing of the Release Notes is tied to the website, more than to release-tools.. So, a change to the process could be part of the 'New Boost Website'. Or, add it later on: "limiting the scope of new features for the initial release." On Sat, Apr 16, 2022 at 4:53 PM Vinnie Falco via Boost < boost@lists.boost.org> wrote:

...

On Sat, Apr 16, 2022 at 2:49 PM Peter Dimov via Boost wrote:

...
We could, e.g. have meta/changelog.json in each library that holds the per-library changes, and generate the release notes from that.

Yes that is possible although it has more to do with the release process (which Sam maintains).

Sam?

Thanks

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

Stefan Seefeld

1:19 a.m.

On 2022-04-16 17:53, Vinnie Falco via Boost wrote:

...

...
We could, e.g. have meta/changelog.json in each library that holds the per-library changes, and generate the release notes from that. Yes that is possible although it has more to do with the release

On Sat, Apr 16, 2022 at 2:49 PM Peter Dimov via Boost wrote: process (which Sam maintains).

In that case I would suggest that we discuss such structural & process improvements *before* we start to think of a website redesign. Otherwise we'll just perpetuate the same errors we made in the previous iteration(s). Stefan -- ...ich hab' noch einen Koffer in Berlin...

Vinnie Falco

5:02 a.m.

On Sat, Apr 16, 2022 at 6:19 PM Stefan Seefeld via Boost wrote:

...

In that case I would suggest that we discuss such structural & process improvements *before* we start to think of a website redesign. Otherwise we'll just perpetuate the same errors we made in the previous iteration(s).

No, because the current site is dated and lacking the features to take us where we want to go. Beman Dawes was a great founder and we have him to thank for Boost and for the contributions to the C++ standard, among other things. Unfortunately he is no longer with us, and our institutions are failing. The committee doesn't look to Boost for inspiration anymore, preferring to design its own components instead of looking to established practice. Technical conversations are dispersed from the mailing list and into silos such as GitHub, Slack, or reddit. It takes increasing time to find a review manager, and fewer people write reviews. The pace of arrival of newcomers to Boost whether it is in terms of proposing new libraries, contributing to existing libraries, or discussing those libraries on the list, has slowed. There is less activity. The reality is that the foundations of Boost need to be refreshed, and this is not going to come from people who are still browsing the mailing list using the command line. Boost needs an infusion of vigor, ideas, and social technology; but most importantly it needs new people and new leaders or else it will continue to fossilize. Boost needs Milennials, Zillennials, Gen Z, and soon Gen A. Attracting these cohorts means speaking their language, and it is not the language of GNU Mailman [1]. It is the language of social media. Apps which are accessible on desktops, laptops, tablets, but also phones. Of apps that effortlessly connect developers together through videos, images, message-based discussions, live chat, video chat, and audio chat. Apps for sharing code (GitHub), apps for compiling code (compiler-explorer). It is the apps which hold the attention of C++ users by delivering to them the information that they need. Instant access to programming best practices, code snippets ready for copying and pasting, powerful libraries with good documentation and permissive licenses that are ready to be incorporated into a larger work with just a click. But also access to a growing community of the very best experts that the C++ language has to offer. Experts who have published libraries that are distributed with almost every version of Linux. In short, access to Boost library authors. To revitalize Boost and C++ we must make our talent and expertise available to the next generation so the individuals who are motivated to strive and achieve the most they can will have the resources and information at their fingertips for them to learn and grow. To achieve this we will build a social media platform on boost.org where all C++ users can visit to learn from the best, find the best libraries, share their techniques and ideas, and build the new tools we need to make continued progress. A living, breathing website with an infinitely scrolling list of user-generated, C++ related content. With avatars, personal profiles, badges, and social scores for participation to encourage engagement. In other words, "A Home Page for C++". We as authors must not only build and embrace a new boost.org but we must attract and cultivate the next generation of library creators so that Boost will continue to thrive well into the future. I hope everyone will join me as we take steps on this journey. Thanks [1] The mailing list functionality still needs to be available to power-users who benefit from consolidated access to all their communities. This will be implemented in the new site.

James E. King III

16 Apr 16 Apr

9:56 p.m.

On Sat, Apr 16, 2022 at 5:49 PM Peter Dimov via Boost wrote:

...

Vinnie Falco wrote:

...
We are adding a database, and this kind of feature will be possible in theory. But, in order to ensure that we actually get this thing done we are limiting the scope of new features for the initial release. We aren't touching the documentation and we are striving to make few to no changes in how the release notes are published.

Fixing the way the release notes are published would be pretty useful.

We could, e.g. have meta/changelog.json in each library that holds the per-library changes, and generate the release notes from that.

I have to disagree with that. GitHub provides us with labels, and people should be using reasonable check-in comments. Instead of having a single collision file like changelog (I have seen this on django-simple-history and it isn't pretty) it would be much better to have a label for a commit that should be included in the release notes and pull the first line of that commit into the release notes with a link to the pull request that it was associated with. This would be more automated and cause far less commit collisions. Using a label like `release-note-worthy` to faciliate this would also allow a project maintainer to decide what is worthy by modifying the labels. - Jim

Peter Dimov

9:59 p.m.

James E. King III wrote:

...

I have to disagree with that. GitHub provides us with labels, and people should be using reasonable check-in comments. Instead of having a single collision file like changelog (I have seen this on django-simple-history and it isn't pretty) it would be much better to have a label for a commit that should be included in the release notes and pull the first line of that commit into the release notes with a link to the pull request that it was associated with.

I don't think this works well in practice. I did suggest that same thing once to Daniel James (when he was still maintaining the website) and he correctly disabused me of that notion. Commit messages just don't good release notes make.

Andrey Semashev

10:10 p.m.

On 4/17/22 00:56, James E. King III via Boost wrote:

...

On Sat, Apr 16, 2022 at 5:49 PM Peter Dimov via Boost wrote:

...
Vinnie Falco wrote:

...
We are adding a database, and this kind of feature will be possible in theory. But, in order to ensure that we actually get this thing done we are limiting the scope of new features for the initial release. We aren't touching the documentation and we are striving to make few to no changes in how the release notes are published.

Fixing the way the release notes are published would be pretty useful.

We could, e.g. have meta/changelog.json in each library that holds the per-library changes, and generate the release notes from that.

I have to disagree with that. GitHub provides us with labels, and people should be using reasonable check-in comments. Instead of having a single collision file like changelog (I have seen this on django-simple-history and it isn't pretty) it would be much better to have a label for a commit that should be included in the release notes and pull the first line of that commit into the release notes with a link to the pull request that it was associated with. This would be more automated and cause far less commit collisions. Using a label like `release-note-worthy` to faciliate this would also allow a project maintainer to decide what is worthy by modifying the labels.

I have experience with generating release notes from commit messages and that doesn't work well in practice. Often, what you want to write in the commit message (which is aimed at library maintainers) is very different from what you want to write in release notes (which is aimed at library users). When you try to combine that the result is not the best for either target audience. Plus, you'll have a problem with grouping an ordering the release notes, if you want something better than chronological order. Generating release notes from commit messages has one advantage - it's cheap and almost automatic. But the result is not very good. I prefer to write release notes explicitly, in a separate document. I'm not in favor of the specific format of JSON as it is not a documentation format and does not support features that are often used in documentation and release notes, such as links, code/preformatted text, bold/italic, numbered and unnumbered lists and so on. We probably won't agree on a single common format of such release notes document, so while I think the idea is good in theory, I don't see how it can be implemented in practice.

Peter Dimov

10:18 p.m.

Andrey Semashev wrote:

...

We probably won't agree on a single common format of such release notes document, so while I think the idea is good in theory, I don't see how it can be implemented in practice.

Well, we already agree on a common format (.qbk), so we can just keep using it. The advantage of JSON is that it supports maps (so that all the versions can be in the same file) but we could in principle use changelog_1_80_0.qbk etc.

Andrey Semashev

10:29 p.m.

On 4/17/22 01:18, Peter Dimov via Boost wrote:

...

Andrey Semashev wrote:

...
We probably won't agree on a single common format of such release notes document, so while I think the idea is good in theory, I don't see how it can be implemented in practice.

Well, we already agree on a common format (.qbk), so we can just keep using it.

Yes, QuickBook would be the obvious candidate, and I would be in favor of it, but we already have libraries that don't use QuickBook. It would be odd to have docs in one format and the changelog in another.

...

The advantage of JSON is that it supports maps (so that all the versions can be in the same file) but we could in principle use changelog_1_80_0.qbk etc.

I think it would be preferable to have a single changelog file. That's the current practice in libraries, and I think, that's the preferred way for the readers (i.e. so that one is able to read and search the changelog back for multiple releases on one page). If we agreed on the changelog format (or a list of formats) we could require certain tags or other formatting tricks so that the website is able to extract release notes for a given release. I don't see this as that big of a problem.

Mateusz Loskot

19 Apr 19 Apr

8:24 a.m.

On Sun, 17 Apr 2022 at 00:29, Andrey Semashev via Boost wrote:

...

On 4/17/22 01:18, Peter Dimov via Boost wrote:

...
Andrey Semashev wrote:

...
We probably won't agree on a single common format of such release notes document, so while I think the idea is good in theory, I don't see how it can be implemented in practice.

Well, we already agree on a common format (.qbk), so we can just keep using it.

Yes, QuickBook would be the obvious candidate

To me, personally, an obvious format for release notes and other auxiliary content is - markup-less as possible - highly human-friendly - directly renderable by GitHub That is, Markdown or AsciiDoc, and QuickBook is not. QuickBook is still a great alternative to DocBook, but since arrival of capable generators and renderers for simpler formats we no longer need such heavy-weight processors. QuickBook is no longer compelling format. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net

Gavin Lambert

4:20 a.m.

On 17/04/2022 10:10, Andrey Semashev wrote:

...

On 4/17/22 00:56, James E. King III wrote:

...
I have to disagree with that. GitHub provides us with labels, and people should be using reasonable check-in comments. Instead of having a single collision file like changelog (I have seen this on django-simple-history and it isn't pretty) it would be much better to have a label for a commit that should be included in the release notes and pull the first line of that commit into the release notes with a link to the pull request that it was associated with. This would be more automated and cause far less commit collisions. Using a label like `release-note-worthy` to faciliate this would also allow a project maintainer to decide what is worthy by modifying the labels.

I have experience with generating release notes from commit messages and that doesn't work well in practice. Often, what you want to write in the commit message (which is aimed at library maintainers) is very different from what you want to write in release notes (which is aimed at library users). When you try to combine that the result is not the best for either target audience. Plus, you'll have a problem with grouping an ordering the release notes, if you want something better than chronological order.

+1 for not generating release notes from commit messages. GitHub does have its own concept of creating releases and release notes that are *associated* with a commit while not actually being part of it -- which means that they can be edited. Though one caveat is that it's difficult to edit them ahead of time. Perhaps this could be used -- as part of the release process, GH's API is used to generate a release (linked to the commit that's actually in the release, with some initial default content that's either autogenerated from commit messages or reads some changelog file that's part of the repository). The library maintainer can edit this after the fact if they need to. The website displays the composite of the release notes from the various library releases (as edited). One downside is that the composite release notes would either need to be dynamically generated or would need to otherwise detect a change to already-published release notes to rebuild. I'm not sure how easy that will be to monitor. As a bonus, having the GH release means that the source code as of that release is downloadable directly from GH, which could simplify modular building (and perhaps trend towards getting rid of the monolithic download entirely? Although that still has its uses).

Gavin Lambert

5:21 a.m.

Mere moments ago, quoth I:

...

GitHub does have its own concept of creating releases and release notes that are *associated* with a commit while not actually being part of it -- which means that they can be edited. Though one caveat is that it's difficult to edit them ahead of time.

Perhaps this could be used -- as part of the release process, GH's API is used to generate a release (linked to the commit that's actually in the release, with some initial default content that's either autogenerated from commit messages or reads some changelog file that's part of the repository). The library maintainer can edit this after the fact if they need to. The website displays the composite of the release notes from the various library releases (as edited).

Actually, looks like they've improved things since I last looked -- you can write draft release notes ahead of time, and they can also auto-generate from commits for you if you want to be lazy (or have a starting point to elaborate on). https://docs.github.com/en/repositories/releasing-projects-on-github/automat... So the release process could probably just use an existing draft if there is one, or trigger automatic generation if there isn't. Either way, the maintainer can then edit it after the fact as needed. And perhaps the release notes on the main boost repo could be the composite (updated by a simple timer, if it's hard to detect an individual library's notes being edited), and then the website could just link to those directly. Quite simple.

Andrey Semashev

8:32 a.m.

On 4/19/22 08:21, Gavin Lambert via Boost wrote:

...

Mere moments ago, quoth I:

...
GitHub does have its own concept of creating releases and release notes that are *associated* with a commit while not actually being part of it -- which means that they can be edited. Though one caveat is that it's difficult to edit them ahead of time.

Perhaps this could be used -- as part of the release process, GH's API is used to generate a release (linked to the commit that's actually in the release, with some initial default content that's either autogenerated from commit messages or reads some changelog file that's part of the repository). The library maintainer can edit this after the fact if they need to. The website displays the composite of the release notes from the various library releases (as edited).

Actually, looks like they've improved things since I last looked -- you can write draft release notes ahead of time, and they can also auto-generate from commits for you if you want to be lazy (or have a starting point to elaborate on).

https://docs.github.com/en/repositories/releasing-projects-on-github/automat...

So the release process could probably just use an existing draft if there is one, or trigger automatic generation if there isn't. Either way, the maintainer can then edit it after the fact as needed.

And perhaps the release notes on the main boost repo could be the composite (updated by a simple timer, if it's hard to detect an individual library's notes being edited), and then the website could just link to those directly. Quite simple.

I would prefer to not rely on GitHub (or other specific services) in core processes, such as library releases. I think one should be able to write release notes locally. And we should be able to switch to a different hosting relatively easily, if such a switch is decided upon.

953

Age (days ago)

956

Last active (days ago)

List overview

Download

23 comments

9 participants

participants (9)

Andrey Semashev
Gavin Lambert
James E. King III
Mateusz Loskot
Niall Douglas
Peter Dimov
Sam Darwin
Stefan Seefeld
Vinnie Falco