Bundlor
  1. Bundlor
  2. BNDLR-281

As a user, I want to write comments in the template.mf

    Details

    • Type: Story Story
    • Status: To Do To Do
    • Priority: Minor Minor
    • Resolution: Unresolved
    • Fix Version/s: None
    • Labels:
      None

      Description

      Sometimes I want to add comments in the template.mf to mark the reason why something ended up in the template.mf. For example to mark a block of imports for a specific service/bean/aop construct, so I can easier reuse these in other bundles.

        Activity

        Hide
        Ben Hale (c) added a comment -

        We stick to the Java Manifest specification for the template files and unfortunately it does not have any provision for comments.

        Show
        Ben Hale (c) added a comment - We stick to the Java Manifest specification for the template files and unfortunately it does not have any provision for comments.
        Hide
        Ric Klaren added a comment -

        That's a pity. It would have been quite helpful. Since the template.mf is more of a meta manifest it would be a good spot I think to be able to add comments. With the standard manifest syntax being restricted as such.

        Show
        Ric Klaren added a comment - That's a pity. It would have been quite helpful. Since the template.mf is more of a meta manifest it would be a good spot I think to be able to add comments. With the standard manifest syntax being restricted as such.
        Hide
        Ben Hale (c) added a comment -

        That's a fair point. We need to do some research about what might not be a legal character currently in the manifest header and use that as a comment character. This is a good idea and I'll try to get to it soon.

        Show
        Ben Hale (c) added a comment - That's a fair point. We need to do some research about what might not be a legal character currently in the manifest header and use that as a comment character. This is a good idea and I'll try to get to it soon.
        Hide
        Ric Klaren added a comment -

        Any word on this? Our project is moving towards 88 bundles now. It would make maintenance of the template.mf files a lot easier. E.g. so we can mark workarounds for sts and bundlor bugs, that can be removed at later moments. Or mark important imports that may seem unimportant at first glance, but which result in ehcache clustering with jgroups not working and things like that..

        We really think this is important. Because it repeatedly hurt us now.

        If comments are implemented it would be nice if the formatting of STS would play nice with the comments and imports (but that's more for another section).

        Thanks!

        Show
        Ric Klaren added a comment - Any word on this? Our project is moving towards 88 bundles now. It would make maintenance of the template.mf files a lot easier. E.g. so we can mark workarounds for sts and bundlor bugs, that can be removed at later moments. Or mark important imports that may seem unimportant at first glance, but which result in ehcache clustering with jgroups not working and things like that.. We really think this is important. Because it repeatedly hurt us now. If comments are implemented it would be nice if the formatting of STS would play nice with the comments and imports (but that's more for another section). Thanks!
        Hide
        Ben Hale (c) added a comment -

        So I've been talking this over with other members of the team, and there isn't really a great solution that we've found yet. It boils down to the fact that while we could potentially support a comment that was non-spec compliant, it would break every bit of tooling around manifests. In other words, we'd essentially need to re-implement the Eclipse Manifest editor that we build on in STS just to be able to support it.

        The preferred solution is that comments are somehow spec-compliant but perhaps removed by Bundlor when the manifest is created. So for example:

        Manifest-Version: 1.0
        
        Bundlor-Comment-1: Owned by us
        Bundle-SymbolicName: com.foo
        
        Bundlor-Comment-2: A special version
        Bundle-Version: 1.0.0
        

        I'll be the first to say that I'm not a fan of this as it's ridiculously verbose. Something like this works as well:

        Manifest-Version: 1.0
        
        Comment: Owned by us
        Bundle-SymbolicName: com.foo
        
        Comment: A special version
        Bundle-Version: 1.0.0
        

        but only if you're willing to ignore the warning about a duplicate definition of the Comment header.

        What might be nice would be:

        Manifest-Version: 1.0
        
        #: Owned by us
        Bundle-SymbolicName: com.foo
        
        #: A special version
        Bundle-Version: 1.0.0
        

        but the # symbol isn't legal in a header's name.

        What are your thoughts on a standards compliant solution for this?

        Show
        Ben Hale (c) added a comment - So I've been talking this over with other members of the team, and there isn't really a great solution that we've found yet. It boils down to the fact that while we could potentially support a comment that was non-spec compliant, it would break every bit of tooling around manifests. In other words, we'd essentially need to re-implement the Eclipse Manifest editor that we build on in STS just to be able to support it. The preferred solution is that comments are somehow spec-compliant but perhaps removed by Bundlor when the manifest is created. So for example: Manifest-Version: 1.0 Bundlor-Comment-1: Owned by us Bundle-SymbolicName: com.foo Bundlor-Comment-2: A special version Bundle-Version: 1.0.0 I'll be the first to say that I'm not a fan of this as it's ridiculously verbose. Something like this works as well: Manifest-Version: 1.0 Comment: Owned by us Bundle-SymbolicName: com.foo Comment: A special version Bundle-Version: 1.0.0 but only if you're willing to ignore the warning about a duplicate definition of the Comment header. What might be nice would be: Manifest-Version: 1.0 #: Owned by us Bundle-SymbolicName: com.foo #: A special version Bundle-Version: 1.0.0 but the # symbol isn't legal in a header's name. What are your thoughts on a standards compliant solution for this?
        Hide
        Ben Hale (c) added a comment -

        So, after even more discussion we're thinking about going down the route of having two supported template formats, either a manifest or a properties file. The properties file route gives us a different (in my opinion better) line continuation strategy, comments, and even blank lines to use as block separators.

        The downside is that the tooling support for this might be a bit delayed as our Eclipse team has other priorities.

        Any thoughts on this alternative?

        Show
        Ben Hale (c) added a comment - So, after even more discussion we're thinking about going down the route of having two supported template formats, either a manifest or a properties file. The properties file route gives us a different (in my opinion better) line continuation strategy, comments, and even blank lines to use as block separators. The downside is that the tooling support for this might be a bit delayed as our Eclipse team has other priorities. Any thoughts on this alternative?
        Hide
        Ric Klaren added a comment -

        The 'Bundlor-Comment-1..n' solution is indeed not the prettiest.

        The multiple Comment: is probably also not practical (at least which comment ends up in the generated manifest?) It feels a bit 'hackish' like the first.

        The latter would be the nicest. I've got no emotional attachment to the manifest spec. It's a horrible format. So the two formats solution would have my preference.

        XML is also not the nicest format for a user, but it could also serve pretty well and it scales better than property files (should one ever want nesting, and an XSD gets you syntax checks and completion for free). At least I'm would also be delighted with an include mechanism. (adding the same bit of imports for some specific AOP constructs gets a bit stale after the first few bundles)

        The JSON format that is used in some spring dm server config files btw reads better than XML. But no XSD's etc. there.

        I personally use the plain text mode to edit manifests/template.mf/test.mf etc, so I can live without most of the UI around manifests/templates. The UI bits only slow down, since I have to click through to the manifest tab. (I personally prefer plain text with good completion, over a slow point click interface. With plain text I can copy paste a class not found exception/or the likes from the problem view into the template then strip out the error messages, regenerate, and be on my merry way. I must say that I've been using spring dm server and sts tooling since it came out and I think I've never ever used the point click UI to edit a manifest/template). Assuming of course that STS can pick up the new format and generate a manifest from it, else the use would become less again.

        Show
        Ric Klaren added a comment - The 'Bundlor-Comment-1..n' solution is indeed not the prettiest. The multiple Comment: is probably also not practical (at least which comment ends up in the generated manifest?) It feels a bit 'hackish' like the first. The latter would be the nicest. I've got no emotional attachment to the manifest spec. It's a horrible format. So the two formats solution would have my preference. XML is also not the nicest format for a user, but it could also serve pretty well and it scales better than property files (should one ever want nesting, and an XSD gets you syntax checks and completion for free). At least I'm would also be delighted with an include mechanism. (adding the same bit of imports for some specific AOP constructs gets a bit stale after the first few bundles) The JSON format that is used in some spring dm server config files btw reads better than XML. But no XSD's etc. there. I personally use the plain text mode to edit manifests/template.mf/test.mf etc, so I can live without most of the UI around manifests/templates. The UI bits only slow down, since I have to click through to the manifest tab. (I personally prefer plain text with good completion, over a slow point click interface. With plain text I can copy paste a class not found exception/or the likes from the problem view into the template then strip out the error messages, regenerate, and be on my merry way. I must say that I've been using spring dm server and sts tooling since it came out and I think I've never ever used the point click UI to edit a manifest/template). Assuming of course that STS can pick up the new format and generate a manifest from it, else the use would become less again.

          People

          • Assignee:
            Unassigned
            Reporter:
            Ric Klaren
          • Votes:
            2 Vote for this issue
            Watchers:
            3 Start watching this issue

            Dates

            • Created:
              Updated:
              First Response Date: