Rene Rivera
On Mon, Jan 4, 2016 at 12:46 PM, Louis Dionne
wrote: Dear list,
Currently, all Boost libraries are required to have a meta/libraries.json file at their root, which contains some meta-data describing the library. As I understand it, this meta-data is then used to generate the list of all libraries with their description when a release is done.
That's one use.
If there are other uses, could you please elaborate? This is not rhetorical; such uses would point out other places that need to be changed to accommodate my proposal.
I find having such a directory at the root of every library annoying, since it clutters it. Furthermore, for metaprogramming libraries, the name can be slightly confusing since meta/ might be expected to contain something different.
1. I don't see how it can be confusing to have that dir.
If not confusing, it can definitely be surprising. The convention for storing meta data and configuration data is to use dotfiles, not meta/ directories. Also, my point is not only about confusion, but mostly about clutter. The meta/ directory at the root of Hana appears in my editor, my file browser and everywhere else as a directory. It is given the same priviledged place as other directories such as include/, when it should be a mere detail.
3. The contents of the meta dir are not restricted to Boost. The information in it could be used more generally.
I think it is very unlikely that any organization beyond Boost itself is using this data. But even then, I'm not proposing to take this data away, merely to support a more idiomatic way of providing it.
4. We are likely going to add more data files to that dir for other uses. For example it would be convenient to add release notes data in there.
The argument of "we might use it in the future" is not a very strong one to me, since the meta/ directory has been used for years for the same purpose without change, AFAICT. Also, as a side note, I would probably oppose storing release notes in such a directory. Some libraries are also released on their own, and it would be messy to store Boost-specific release notes in there. Plus, some people might want to use GitHub to provide release notes (this is my case). And even if we were to always include release notes in a library, we could argue that using a CHANGELOG file or similar is more in line with existing practice. However, if having a single .boost file honestly seems too restrictive for your planned use cases, and if you were to cast an influential NO vote on this proposal for that reason, I would 1. Be suspicious about use cases so complex they can't be handled by a JSON file (my 400LOC Travis script is basically a JSON file!) 2. Suggest using a .boost _directory_ instead of a single file
I propose that we allow libraries to specify their metadata in a `.boost` file located at their root. Using a dotfile is the most common way of providing information for an external service (for example .travis.yml), and dotfiles are usually more discrete when viewing the project in an editor. Furthermore, making `boost` part of the filename is more descriptive.
I don't see the point. It's a Boost library. It's already has "Boost" in the "name".
While it is obvious that Boost.XXX is a Boost library from its name, it is less than obvious what purpose serves a meta/libraries.json file at the root of such a library, and even less a meta/ directory alone. Using a .boost file instead says two things: 1. It consists of metadata, configuration or other nitpicks, since it's a dotfile and this convention is widely used. 2. This metadata or configuration is related to Boost, since it has boost in the filename. What if Travis had decided to use a ci/ directory instead of a .travis.yml file? Clearly, using Appveyor and Travis at the same time would have been confusing, since both of them are CIs. Using .travis is just more focused, and it carries the intent better.
I have submitted a pull request to BPM [1] adding the ability to fetch the meta data in a .boost file. The meta-data can still be provided in meta/libraries.json, so this should not affect existing libraries.
It would as it's more maintenance and confusion as to where to have that data. And as was pointed out that's not the only consumer of that data.
As Glen suggested, we could also move all the modules to the dotfile approach. Otherwise, I think you can see from my pull requests that the amount of added maintenance is quite small. Plus, unless we realize the the whole world needs to be changed to implement this proposal, I volunteer to do it. I have already started doing so, but other places might need to be changed too. I would of course need some cooperation from people that are more knowledgeable about the Boost infrastructure than I am.
- Perhaps we could store the meta-data for all the libraries in the same
place, and get rid of the individual meta-data files?
No. The point of having that dir in each library is to decentralize the information so that it can be easily managed by the individual authors instead of needing continual release manager intervention.
Ok, let's keep it decentralized.
- If this suggestion is accepted, is there more to modify than BPM?
Yes. There are other tools (website & release related) . And of course documentation.
I already submitted a PR to the website. I wasn't able to find any other related reference to meta/, libraries.json or a combination of these when searching through the code base. Feel free to point out to me anything that would have been left out.
In summary, I'm against this as the perceived benefit is minimal compared to the "implementation effort".
In summary, 1. Using dotfiles allows other tools to see this meta information as it is, and to deal with it properly. 2. Using dotfiles sticks to a well-established convention for storing meta data in a non-intrusive way: Travis => .travis.yml Git => .git, .gitignore, .gitmodules, ... Bash => .bashrc, .bash_profile, .bash_history, ... Hg => .hgignore Rbenv => .rbenv LLDB => .lldb ... Boost => meta/libraries.json Can't we just do like everybody else? I would like to invite you to reconsider your opinion about this proposal. Since we're talking about naming, it's of course not a killer change and the benefits are hence not gigantic. But the benefits are nonetheless there, and a step in the good direction is worth taking, even if it is a small one. Regards, Louis