Release 0.4.0

[saraedum]

The last release of this has been two years ago. Would you mind creating a new release so this can be more easily packaged by distributions?

Here's what needs to happen I think before this can happen:

• [x] Include patches from https://github.com/conda-forge/staged-recipes/pull/9745/files (#147)
• [x] Check that README is accurate (@saraedum has not checked every bit but it should be mostly correct with #150)
• [x] Add 0.4.0 to the ChangeLog (#153)
• [x] Build docker images (#150)

[foonathan]

I am mostly wondering what you think about this (you probably do not care much about this project at the moment.) I am happy to polish this more with your input.

Yeah, I am not really motivated to work on standardese at the moment (and I didn't have the time for anything the past couple months and until October anyway).

I had this great vision for the project, to write a tool that fully understands C++ and generates the correct documentation, but the more I did, the more I realized that this is just not possible in the way I wanted it, which demotivated me a lot.

I am not sure when I want to continue working on it, which is a shame because people seem to use it/like it, so I don't think I should keep owning the project. If you (or anyone else) like to step up, I'd be willing to transfer ownership.

[saraedum]

I am mostly wondering what you think about this (you probably do not care much about this project at the moment.) I am happy to polish this more with your input.

I had this great vision for the project, to write a tool that fully understands C++ and generates the correct documentation, but the more I did, the more I realized that this is just not possible in the way I wanted it, which demotivated me a lot.

Could you elaborate a bit on what kinds of things were not possible?

I am not sure when I want to continue working on it, which is a shame because people seem to use it/like it, so I don't think I should keep owning the project. If you (or anyone else) like to step up, I'd be willing to transfer ownership.

I might be using standardese professionally quite a bit so I should be able to allocate some time for its maintenance. At the same time, I do not feel ready to take sole ownership of the project yet. But if some more people would join the effort, I would not mind to be a core member of the standardese team.

[foonathan]

Well, f you're writing libraries with advanced template metaprogramming, the C++ you write is a lot different from the way the API is supposed to look. The best way is to just manually write the synopsis you want to have in that case.

And because I am writing a lot of advanced template metaprogramming libraries, standardese isn't really useful for me anymore.

[jansende]

Would you mind elaborating on this point? The way you write the metaprogramming libraries cannot be interpreted by standardese? Or it's just cumbersome to write the correct standardese syntax?

[foonathan]

standardese works fine, it just doesn't show what I necessarily want to say.

For example, I might have a detail base class to conditionally disable copy/move constructors, but in the documentation I just want to list the constructor and say it is conditionally disabled. I've started working on supporting it, but it doesn't quite work yet.

It is a lot of work to fully handle those things, for my use cases it is just easier to manually write the synopsis.

[jansende]

Ah okay. I discovered standardese by chance today and had a look around the repo. Being that I have lots of compile time computations as well, I was wondering what the problem is. Thanks for the answer.

[foonathan]

standardese is probably going to handle the code better than Doxygen. But it is not quite at the level I want.

[saraedum]

After working with this quite a bit more, I figured that standardese will be the tool that I'll be using for quite some documentation tasks. So I am happy to do a big chunk of maintenance for the next year at least.

I guess a typical process would be to move standardese into a standardese organization on GitHub? What do you think @foonathan?

@foonathan what's the status of the submodules (ThreadPool, cppast, cmark) and recursively their dependencies? Which of these are essentially specific to standardese? (And should then probably be moved as well.)

[foonathan]

That's good to hear, thank you!

• ThreadPool: I think it is no longer maintained by the original author, but it is just a single header file that works well.
• cppast: this is a library written by me, I'll continue maintaining it
• cmark: this is another third-party project, I'm using the fork by GitHub, it is semi-actively maintained

I could create an organization or I can just transfer ownership over to you, if you want.

[saraedum]

I created a standardese organization. You should have received an invitation.

Feel free to add people and transfer repos to this organization. I'll ask someone to come up with a logo for this if you don't have one already.

[foonathan]

Alright, I have transferred standardese (as you can tell).

Feel free to do whatever you want with it :) I will hang probably hang around in the issue tracker and PRs, but will probably not commit much. Have fun!

[saraedum]

Thank you. I'll likely CC you very frequently. Feel free to ignore these (but I would of course be very happy about any comments.) I am sure that we'll happen to break some design ideas that we don't get initially as we are getting to know the code base better. :) As I said, any comments are always very welcome.

[foonathan]

I'll be happy to help in any way I can. I'll also announce it on my blog soon and write a detailed post-mortem why I abandoned it. You should probably remove the patreon link from the Readme. How should we handle the license?

[saraedum]

Do you mean the copyright notice in the license? I'm happy with keeping it the way it is for the time being, probably adding "and the standardese contributors". I'd probably want to add an AUTHORS file or something like that that lists all the contributors for copyright purposes.

[foonathan]

Yes, that sounds good.

[jansende]

All hail to our new overlord! 😆 @saraedum already any concrete plans?

[saraedum]

@jansende, let's chat on gitter.

[bresilla]

I created a standardese organization. You should have received an invitation.

Feel free to add people and transfer repos to this organization. I'll ask someone to come up with a logo for this if you don't have one already.

What do you thing about this logo! I made yesterday after seeing this project will get back on track again. The logo is an "S" but divided in three parts just like "///" for standardese comments :)

Anyways, here is the SVG gist: https://gist.github.com/bresilla/cebf2a0a2a66ae719b4ec60a86e5d641

Feel free to use any way you want, or just ignore all the same.

I am just happy that this project will see a fresh restart. I am using standardese quite a lot too, so hopefully soon I'll be able to join and contribute code too :)

[bresilla]

Meanwhile wouldn't mind start working on a static website (documentation) for the project. I'll have some time to do that by the end of the month!

I could use HUGO as a static builder. And maybe later on the road, we could think of ways how to directly integrate the standardese output to HUGO's static building language too (or even Markdown).

This would be awesome, as HUGO is already awesome to build different layouts and themes (even for documentations). I am learning compilers those days, and i am building a toy language, and was thinking that having a tool that spits out documentation and then can easily be picked up by static page builders (HUGO, JEKYLL and whatever is there) would be amazing. Standardese already does that, it just needs a better integration. I will spend some time into that ...

Anyways :)

[saraedum]

@bresilla thanks for the awesome logo! I'll create a new issue for the documentation/website…thanks for taking the lead on that!

[bresilla]

@bresilla thanks for the awesome logo! I'll create a new issue for the documentation/website…thanks for taking the lead on that!

I was thinking more into creating a separate repository inside the standardese organisation, called website and use that to build a website with Github Pages

https://pages.github.com/

So there would be a separate repository called website (or whatever you want) and then there there would be a folder "/docs" that GitHub Page would pick up the index.html file and serve as website.

What do you think?

[foonathan]

just fyi: the website repo needs to be called standardese.github.io

I'm so happy that you seem to be bringing this one back to live, thanks a lot!

[saraedum]

To make the life of packager's easier, I would like to move to semantic versioning. So the next release would probably be 1.0.0 (after 0.3-4 which probably translates to 0.3.4 in semver.) I know that to some people 1.0.0 sounds like "first stable release" which it is definitely not. But it contains afaik breaking changes from 0.3-4 so 1.0.0 is the logical version number.

I'd start with 1.0.0-rc.0 and see whether things check out when packaging on conda-forge and docker. Once that looks alright, I'll create the actual 1.0.0 release. What do you think?

[jzakrzewski]

https://semver.org/#spec-item-4 So I see no pressure on calling it 1.0.0 if it's not really intended to be.

[saraedum]

Cool. Wasn't aware of that. So 0.4.0 then?

[jzakrzewski]

Yeah, I'd go 0.4.0. Would also probably be nice to drop a line somewhere in docu that this project adheres to semver just to make it clear. I mean there are a lot of projects using x.y.z versioning but not really using semver.

[jansende]

@saraedum @jzakrzewski Although it is allowed to stay at 0.x.x, it still might be nice to upgrade to 1.0.0 just to mark the changes as not backwards compatible.

Regardless of what version number you choose, you could mark it as unstable in the version log, plus you could add a -alpha modifier to the version number never upgrading it to a full version (as long as you are developing). For example: 1.0.0-alpha, 1.1.0-alpha, 1.1.5-alpha, ...

[saraedum]

I wouldn't add -alpha since it's not an alpha as opposed to some previous stable version. I think I prefer 0.4.0, it communicates more clearly that this isn't stable yet.

standardese is not widely packaged (actually, is it anywhere but in the AUR?) so people won't accidentally upgrade and hate us for breaking changes :)

[saraedum]

Now, I have no clue what to put in the Release Notes for 0.4.0-rc0. I never used the released version of standardese but only the develop branch so I have no idea what has actually changed.

Does someone know and would like to point out the major points?

[foonathan]

It's basically a complete internal rewrite using cppast and the GitHub fork of cmark with parsing extensions. It has more "frontend" features than master but I hadn't re-implemented templating yet.

[saraedum]

I put a little todo at the top of this issue. I'll take care of the patches and the docker images. If anybody wants to take care of the README and/or ChangeLog please feel free to plunge forward :)

[foonathan]

fyi: https://foonathan.net/2019/11/standardese-post-mortem/