[BPM] Supporting an alternative to meta/libraries.json
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. 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. 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 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. Related questions that we might want to consider: - Should it be .boost.json instead of .boost? - Perhaps we could store the meta-data for all the libraries in the same place, and get rid of the individual meta-data files? - If this suggestion is accepted, is there more to modify than BPM? Regards, Louis [1]: https://github.com/boostorg/bpm/pull/1
Louis wrote:
Should it be .boost.json instead of .boost?
I'd prefer it as .boost, no need for an extension.
I find having such a directory at the root of every library annoying, since it clutters it.
Surely every Boost library providing an index.html at the root is equally annoying. :-) Glen -- View this message in context: http://boost.2283326.n4.nabble.com/BPM-Supporting-an-alternative-to-meta-lib... Sent from the Boost - Dev mailing list archive at Nabble.com.
Glen Fernandes
Louis wrote:
Should it be .boost.json instead of .boost?
I'd prefer it as .boost, no need for an extension.
I find having such a directory at the root of every library annoying, since it clutters it.
Surely every Boost library providing an index.html at the root is equally annoying.
It is annoying, although I don't think it's required. From my understanding, this is directed by what the links in boost/libs/libraries.htm point to. For example, when I submitted my pull request adding Hana to the main Boost repository [1], I added the following entry to libs/libraries.htm: <li><a href="hana/doc/html/index.html">...</a>...</li> This way, unless I'm mistaken, the library only needs to provide the doc/html/index.html file. Regards, Louis [1]: https://github.com/boostorg/boost/pull/98
Louis wrote:
From my understanding, this is directed by what the links in boost/libs/libraries.htm point to.
I'm not so sure about that. Take Boost.Graph, whose entry in libraries.htm is in the form of: < a href="graph/doc/table_of_contents.html" >graph< /a > Yet visiting www.boost.org/libs/graph goes through: http://www.boost.org/libs/graph/ 301 Moved Permanently http://www.boost.org/doc/libs/release/libs/graph/ 303 See Other http://www.boost.org/doc/libs/1_60_0/libs/graph/ 301 Moved Permanently http://www.boost.org/doc/libs/1_60_0/libs/graph/doc/index.html 200 OK It hits graph's root level index.html which contains: < meta http-equiv="refresh" content="0; URL=doc/index.html" > Glen -- View this message in context: http://boost.2283326.n4.nabble.com/BPM-Supporting-an-alternative-to-meta-lib... Sent from the Boost - Dev mailing list archive at Nabble.com.
Glen Fernandes
Louis wrote:
From my understanding, this is directed by what the links in boost/libs/libraries.htm point to.
I'm not so sure about that.
Take Boost.Graph, whose entry in libraries.htm is in the form of: < a href="graph/doc/table_of_contents.html" >graph< /a >
Yet visiting www.boost.org/libs/graph goes through:
http://www.boost.org/libs/graph/ 301 Moved Permanently http://www.boost.org/doc/libs/release/libs/graph/ 303 See Other http://www.boost.org/doc/libs/1_60_0/libs/graph/ 301 Moved Permanently http://www.boost.org/doc/libs/1_60_0/libs/graph/doc/index.html 200 OK
It hits graph's root level index.html which contains: < meta http-equiv="refresh" content="0; URL=doc/index.html" >
Ah, you seem to be right. In this case, I think I don't even understand the purpose of the links in boost/libs/libraries.htm. Can anyone shed light on this? Regards, Louis
Louis wrote:
Ah, you seem to be right. In this case, I think I don't even understand the purpose of the links in boost/libs/libraries.htm. Can anyone shed light on this?
That libraries.htm page is what people see when they visit: http://www.boost.org/libs The library root index.html is what people see when visiting: http://www.boost.org/libs/<library> Almost every library's index.html is just the same boilerplate with a different meta redirect to that library's documentation index. I wish that documentation index link could be specified in the library's .boost file instead of requiring every library to have that index.html. Glen -- View this message in context: http://boost.2283326.n4.nabble.com/BPM-Supporting-an-alternative-to-meta-lib... Sent from the Boost - Dev mailing list archive at Nabble.com.
I wrote:
That libraries.htm page is what people see when they visit: http://www.boost.org/libs
Correction: http://www.boost.org/doc/libs/<version>/libs/libraries.htm Glen -- View this message in context: http://boost.2283326.n4.nabble.com/BPM-Supporting-an-alternative-to-meta-lib... Sent from the Boost - Dev mailing list archive at Nabble.com.
Glen Fernandes
Louis wrote:
Ah, you seem to be right. In this case, I think I don't even understand the purpose of the links in boost/libs/libraries.htm. Can anyone shed light on this?
That libraries.htm page is what people see when they visit: http://www.boost.org/libs
The library root index.html is what people see when visiting: http://www.boost.org/libs/<library>
Almost every library's index.html is just the same boilerplate with a different meta redirect to that library's documentation index. I wish that documentation index link could be specified in the library's .boost file instead of requiring every library to have that index.html.
Ah, I understand now. Thanks for the explanation. Having an index.html at the root of a library is IMO very hacky (why should a library's layout be affected by the need for boost.org to redirect stuff around?), but changing this should be attempted in a different discussion. Regards, Louis
Louis, I would suggest making changes to more than BPM, since meta/libraries.json is also consumed by other things[1][2]. In my opinion it would be worth making them: I like the idea of .boost in library root instead of meta/libraries.json. Otherwise Hana will still need meta/libraries.json even if it had a .boost for BPM to consume. Glen [1] https://github.com/boostorg/website/search?q=get_libraries_json&type=Code [2] https://github.com/boostorg/website/search?q=read_libraries_json&type=Code -- View this message in context: http://boost.2283326.n4.nabble.com/BPM-Supporting-an-alternative-to-meta-lib... Sent from the Boost - Dev mailing list archive at Nabble.com.
Glen Fernandes
Louis, I would suggest making changes to more than BPM, since meta/libraries.json is also consumed by other things[1][2].
In my opinion it would be worth making them: I like the idea of .boost in library root instead of meta/libraries.json.
Otherwise Hana will still need meta/libraries.json even if it had a .boost for BPM to consume.
Ah, I didn't know about these usages of meta/libraries.json, but thanks for the heads up. I submitted a pull request to boostorg/website [1]. If anyone sees another place that should be changed to add support for this proposal, please let me know. Regards, Louis [1]: https://github.com/boostorg/website/pull/131
On Mon, Jan 4, 2016 at 12:46 PM, Louis Dionne
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.
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. 2. Having other dirs other than the required ones would not be common. And not something I would recommend. 3. The contents of the meta dir are not restricted to Boost. The information in it could be used more generally. 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. 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".
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.
Related questions that we might want to consider:
- Should it be .boost.json instead of .boost?
Meh. - 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.
- If this suggestion is accepted, is there more to modify than BPM?
Yes. There are other tools (website & release related) . And of course documentation. In summary, I'm against this as the perceived benefit is minimal compared to the "implementation effort". -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail
Rene wrote:
Having other dirs other than the required ones would not be common. And not something I would recommend.
Boost libraries already have directories (and files) other than the required ones. I don't think it is a good idea to restrict this in any way.
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.
Agreed; it makes sense to have this information in each library. Louis' suggestion just affects the format of that information in each library. A 'dot' file in root directory feels like an already established convention.
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.
Yes. More desirable than having to support both formats would be en masse modification of all libraries to change meta/libraries.json to .boost. The matter effort that you raise: If Louis was willing to do the above work, would you still object? I can't imagine library authors objecting. (It's not like anyone objected to: A Wild meta/libraries.json Appears.) Glen -- View this message in context: http://boost.2283326.n4.nabble.com/BPM-Supporting-an-alternative-to-meta-lib... Sent from the Boost - Dev mailing list archive at Nabble.com.
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
On Wed, Jan 6, 2016 at 1:52 AM, Louis Dionne
In summary,
1. Using dotfiles allows other tools to see this meta information as it is, and to deal with it properly.
I don't see how using dofiles, dotdirs or regular directories affect tools. AFAIU, tools are able to access dotfiles/dotdirs the same way they're accessing meta/libraries.json now.
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
FWIW, I hate that some of the examples above spur a bunch of dotfiles in my home directory or local copy of a repository or whatever. I would very much prefer if we had a directory with these files, and possibly not store all sorts of unrelated metadata in a single JSON file. I have no preference on how this directory is named.
Andrey Semashev
On Wed, Jan 6, 2016 at 1:52 AM, Louis Dionne
wrote: [snip]
In summary,
1. Using dotfiles allows other tools to see this meta information as it is, and to deal with it properly.
I don't see how using dofiles, dotdirs or regular directories affect tools. AFAIU, tools are able to access dotfiles/dotdirs the same way they're accessing meta/libraries.json now.
Of course they're able to access them in the same way, but they don't display them in the same way. For example, in my editor, dotfiles appear at the top of the file list. In the Finder, they don't appear at all. I've seen some editors where they are greyed out. On the other hand, the meta/ directory appears as a normal directory, which is annoying. Of course, it's an annoyance we can cope with. But since I'm ready to do the work, and since it impacts virtually nothing (my PRs are backward compatible), why not just go for it?
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
FWIW, I hate that some of the examples above spur a bunch of dotfiles in my home directory or local copy of a repository or whatever. I would very much prefer if we had a directory with these files, and possibly not store all sorts of unrelated metadata in a single JSON file. I have no preference on how this directory is named.
Fine, it would have been better if the whole world had agreed on storing metadata in a meta/ directory in the first place, and if tools had been developped to understand that meta/ is not a directory like the rest. Unfortunately, this is not the case right now, and my opinion is that we should stick to the current common practice instead of diverging for virtually no good reason. If you are worried about not being able to store all you want in a single JSON file, then let's go for a .boost directory with multiple files in it. I don't care, as long as that dotdir (1) does not clutter my folder list (2) has a name that _clearly_ relates to boost, and that is hence unsurprising Regards, Louis
I should have prefaced all my replies with.. I don't feel strongly opposed
to this change. Just more like "meh" ;-) So please take my comments in that
context.
On Tue, Jan 5, 2016 at 4:52 PM, Louis Dionne
Rene Rivera
writes: 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 don't know all of them ATM. Daniel maintains some extra tools that deal with that file. So he will need to tell us.
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.
It's a convention on Unix style systems. Not so much on Windows. For example, Appveyor doesn't use a dotfile (although maybe they support alternate names?) 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.
Personally I consider hiding of information (aka files) by IDEs to be a UI bug. Which is especially painful to me as I spend most of my personal programming time on OSX :-) It also means I had to dig around IDE documentation to disable that bug.
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.
True :-)
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.
Good point.. Although when it comes to infrastructure changes everything works in multi-year time frames. So movement might not be apparent.
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.
You are going to need to mention what goes into here < http://www.boost.org/users/history/version_1_60_0.html> somewhere. And I'd prefer to move away from having authors continually submit PRs to the website for this. 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!)
Sure. Or in my envisioned future use case.. A quickbook file.
2. Suggest using a .boost _directory_ instead of a single file
Renaming the directory seems like a better choice to me.
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.
It's a case of facets. For CIs they are facets of a repository. Which is not really the case for Boost. It's single a Boost library. Now I grant you that it's becoming possible to have a library be independent and a Boost library. So perhaps that's the issue you are trying to resolve? I.e. How to manage a library that has both an independent, outside of Boost, existence and is part of Boost?
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.
If we change.. I prefer to just move everything to the new way. Having multiple supported ways hasn't worked out so well for us in the past ;-) And it's easier to deal with one way for tools (see my other post). 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.
Right. You will definitely need help. At least to go in and merge all the PRs involved in this. Since only admins (aka the release team) has enough privileges to do this unilaterally. And it needs to be unilaterally, since the last time we did such a change (creating that meta dir) it was impossible to get authors to help.
- 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.
I'll try and find the other uses. But I don't know all of them.
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?
We are, historically, not fond of doing it 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.
I always reconsider (although I'm still strongly against cmake.. but that's a different ball of wax) :-D -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail
Rene Rivera
I should have prefaced all my replies with.. I don't feel strongly opposed to this change. Just more like "meh" So please take my comments in that context.
On Tue, Jan 5, 2016 at 4:52 PM, Louis Dionne
wrote: [...]
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 don't know all of them ATM. Daniel maintains some extra tools that deal with that file. So he will need to tell us.
Ok no problem. Let's hope Daniel sees this thread.
[...]
If not confusing, it can definitely be surprising. The convention for storing meta data and configuration data is to use dotfiles, not meta/ directories.
It's a convention on Unix style systems. Not so much on Windows. For example, Appveyor doesn't use a dotfile (although maybe they support alternate names?)
That's true. However, I think that it would be better to adhere to a convention, even if not universal, than to adhere to no convention at all. Also, you are correct in thinking that Appveyor allows customizing the name of the appveyor.yml file.
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.
Personally I consider hiding of information (aka files) by IDEs to be a UI bug. Which is especially painful to me as I spend most of my personal programming time on OSX It also means I had to dig around IDE documentation to disable that bug.
I guess this is personal preference, then. Outside of an IDE, I find it very useful to have commands like `ls` exclude dotfiles and dotdirs by default. But again, you could argue for the contrary, so let's assume this is not a strong argument for or against.
[...]
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.
You are going to need to mention what goes into here < http://www.boost.org/users/history/version_1_60_0.html> somewhere. And I'd prefer to move away from having authors continually submit PRs to the website for this.
Ah, I see.
[...]
2. Suggest using a .boost _directory_ instead of a single file
Renaming the directory seems like a better choice to me.
In retrospect, it probably is a better choice indeed. The changes required to existing tools would also be even more trivial, and we could easily do a batch renaming for all modules. Like I said elsewhere, my problem is not file vs directory, but the way such a file or directory is named.
[...]
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.
It's a case of facets. For CIs they are facets of a repository. Which is not really the case for Boost. It's single a Boost library. Now I grant you that it's becoming possible to have a library be independent and a Boost library. So perhaps that's the issue you are trying to resolve? I.e. How to manage a library that has both an independent, outside of Boost, existence and is part of Boost?
Yes, exactly. When reasonable, I want to minimize the cohesion between Hana and Boost. In its current state, Hana is a completely standalone library, which also happens to work inside the Boost tree. I'd like it to stay that way, since I find it gives me more freedom to use Hana the way I want.
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.
If we change.. I prefer to just move everything to the new way. Having multiple supported ways hasn't worked out so well for us in the past And it's easier to deal with one way for tools (see my other post).
Sure, then I'd be OK with doing a batch rename.
[...]
Right. You will definitely need help. At least to go in and merge all the PRs involved in this. Since only admins (aka the release team) has enough privileges to do this unilaterally. And it needs to be unilaterally, since the last time we did such a change (creating that meta dir) it was impossible to get authors to help.
If I provided a script to do it, could someone from the release team update all the repositories? Such a script should be fairly simple to write, but in comparison creating 100+ PRs and merging them would be quite cumbersome. One problem I see is for those libraries maintained as forks; in this case the original repository would need to be updated, which would require authors to cooperate. But I think all libraries maintained as forks have authors that are around, so it should be doable. Regards, Louis
On Wed, Jan 6, 2016 at 1:50 PM, Louis Dionne
Rene Rivera
writes: On Tue, Jan 5, 2016 at 4:52 PM, Louis Dionne
wrote: [...]
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 don't know all of them ATM. Daniel maintains some extra tools that deal with that file. So he will need to tell us.
Ok no problem. Let's hope Daniel sees this thread.
We'll probably need to start another thread so he notices. I guess this is personal preference, then. Outside of an IDE, I find it very
useful to have commands like `ls` exclude dotfiles and dotdirs by default. But again, you could argue for the contrary, so let's assume this is not a strong argument for or against.
Indeed.. As I add aliases to ls that show the dot files :-) Since it's become popular to hide dot files ;-)
[...]
2. Suggest using a .boost _directory_ instead of a single file
Renaming the directory seems like a better choice to me.
In retrospect, it probably is a better choice indeed. The changes required to existing tools would also be even more trivial, and we could easily do a batch renaming for all modules.
OK, thinking about it more, now that my brain has time.. I think the best I can think of is to have the dir be ".boostlib". It directly communicates the intended use "Stuff about the Boost library". Yes, exactly. When reasonable, I want to minimize the cohesion between Hana
and Boost. In its current state, Hana is a completely standalone library, which also happens to work inside the Boost tree. I'd like it to stay that way, since I find it gives me more freedom to use Hana the way I want.
Interesting that Predef is also that way :-)
[...]
Right. You will definitely need help. At least to go in and merge all the PRs involved in this. Since only admins (aka the release team) has enough privileges to do this unilaterally. And it needs to be unilaterally,
since
the last time we did such a change (creating that meta dir) it was impossible to get authors to help.
If I provided a script to do it, could someone from the release team update all the repositories?
Sure.
Such a script should be fairly simple to write, but in comparison creating 100+ PRs and merging them would be quite cumbersome.
Note, I would prefer if the script did *everything* needed to do the rename. Which means starting from nothing, doing the clones, branch switches, renames, commits, and pushes.
One problem I see is for those libraries maintained as forks; in this case the original repository would need to be updated, which would require authors to cooperate. But I think all libraries maintained as forks have authors that are around, so it should be doable.
Wouldn't they get merge conflicts and be forced to resolve them? -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail
On Wed, Jan 6, 2016 at 1:50 PM, Louis Dionne
Rene Rivera
writes: On Tue, Jan 5, 2016 at 4:52 PM, Louis Dionne
wrote: [...]
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 don't know all of them ATM. Daniel maintains some extra tools that deal with that file. So he will need to tell us.
Ok no problem. Let's hope Daniel sees this thread.
We'll probably need to start another thread so he notices.
I sent him a private email to notify him of the thread.
[...]
OK, thinking about it more, now that my brain has time.. I think the best I can think of is to have the dir be ".boostlib". It directly communicates the intended use "Stuff about the Boost library".
I am not strongly attached to the exact name of the directory. I do find that .boost is prettier, but I don't really care. I'll use .boostlib when preparing pull requests.
[...]
Such a script should be fairly simple to write, but in comparison creating 100+ PRs and merging them would be quite cumbersome.
Note, I would prefer if the script did *everything* needed to do the rename. Which means starting from nothing, doing the clones, branch switches, renames, commits, and pushes.
Sure, I think that's the best way to go too. I reckon the changes should be made to the `develop` branches of each library. The changes would then eventually merged to `master` when preparing the next release. Is this correct?
One problem I see is for those libraries maintained as forks; in this case the original repository would need to be updated, which would require authors to cooperate. But I think all libraries maintained as forks have authors that are around, so it should be doable.
Wouldn't they get merge conflicts and be forced to resolve them?
I guess that would be a viable path too, although it might be better to ask these authors the permission before applying the changes, for politeness. What I propose is the following plan: 1. I'll prepare pull requests for the tools that need to be changed. That will most likely require Daniel James to give me some input. 2. I'll prepare a script that a release manager can run to apply and commit the changes to individual libraries. 3. I'll send an email to this mailing list, explaining what changes are about to be rolled out. We should give some time period for people to oppose to the changes, if they so desire. Something like 1 week seems reasonable? 4. Once the period is done, if it is clear enough that people are okay with this change, a release manager can roll out the changes and merge my pull requests on the tools all at once. Does this plan seem reasonable? Regards, Louis
On 13 January 2016 at 15:49, Louis Dionne
Ok no problem. Let's hope Daniel sees this thread.
We'll probably need to start another thread so he notices.
I sent him a private email to notify him of the thread.
I think this is a bad idea, the advantages of such a change are smaller than the disruption it would cause. Having two different locations would be an issue, because it would be likely that people won't realise that they have to deal with that - especially if one location is hidden. So if someone writes a script using this data, they'd miss some of it. The alternative is to move the files in every module, which would result in a pointless discontinuity. It's also not true that dotfiles are idiomatic here. Since you were addressing package management, that's a fairly good place to look for examples. I had a look at package management systems for several languages (maven for java, nuget for c#, gopm for go, cpan for perl, npm for javascript, composer for php, pip for python, gems for ruby) and only gopm uses dotfiles. That's hardly an established idiom. But I don't really think a third party tool is an appropriate place to look. This is dealing with a boost specific problem, and has no ambition to be a general purpose tool. The 'meta' directory is intended to be part of the standard boost directory layout, and follows the established style. Of course dotfiles also don't have any special meaning on windows, and many of our developers are windows based, so they'd just be weird for them. And on platforms where they are hidden, that's a problem, as they're not discoverable. The whole point of these files is to make it easy for maintainers to update information, even if they don't know about the system in advance. This is also the reason why the file needs to be short. I find the suggestion that the file's path should have had a boost specific element more convincing, and if that had been suggested when I was first setting this up, I would have changed it. But I feel it's too late now, at this point stability is more important, and a path collision with another tool/service seems very unlikely. FWIW none of my scripts actually require a module to have this file, the data can be managed directly in the website. I created them using pull requests with a note saying that they weren't required. But others wanted them to be in every module, so that's why it's required now. And since you were wondering why it's a directory, there was a vague plan to use a similar mechanism for the expected test results, but no one has been keen enough to actually implement it.
participants (5)
-
Andrey Semashev -
Daniel James -
Glen Fernandes -
Louis Dionne -
Rene Rivera