On 23/04/2015 4:32 AM, Tomasz Borek wrote:
I'm actually quite surprised by this thread. My perspective on adding a
comment tag is different to most here:
A)nother tag in XML *MIGHT* help with letting me know why XYZ was added. IF
people will remember to fill it out. And XYZ removal cuts out the comment
as well, so if somebody removed a dependency / other I was relying on, I'm
no smarter.
If the person read the comment and still deleted the dependency, at
least they knew what the impact would be on the build.
One has to assume that people who are allowed to change software are
responsible.
B)loated / bigger XML, another tag to fill in, for each dependency, yay! :/
I would only use it where the need for the dependency is obscure or as
in my example Use Case 2 the version can not be changed for a known
reason that might not be known by others.
You are right that putting useless comments would not be helpful.
C)hanges monitoring is what SCM is designed for. Just have your POM under
version control and you'll see when what and why was removed/changed/added.
Hoping to avoid a retrospective analysis and search for a perpetrator by
letting people know in advance that the pom statements that look like
they should be fixed, are actually there for a reason.
For me the idea ain't appealing, it's actually slightly on the "no, I don't
want" side.
pozdrawiam,
LAFK
2015-04-21 0:31 GMT+02:00 Jim Klo <[email protected]>:
On Apr 20, 2015, at 2:38 PM, Ron Wheeler <[email protected]>
wrote:
On 20/04/2015 4:55 PM, Jim Klo wrote:
Comments inline below..
On Apr 20, 2015, at 10:44 AM, Ron Wheeler <[email protected]
<mailto:[email protected] <[email protected]>>>
wrote:
RDF sounds like overkill. There is no reason why a comment could not be a
URI but I am not sure that you want to mandate that.
Use Case 1 link to web resource
<dependency comment="http://blog.artifact-software.com/tech/?p=191”>
Having dealt with this sort of thing on other projects, linked comments
sound good at first but ultimately become a very bad idea IMO. This creates
a non-idempotent and brittle link scenario where the comment url is out of
synch with the content in the POM.
Use Case 2 lots of in-line deatils
<dependency comment="added to support PDF output">
<groupId>org.apache.xmlgraphics</groupId>
<artifactId>fop</artifactId>
<version comment="Can't use version 2.x see
FOP-3423">1.0</version>
<optional comment="set to true to get text in black on
white">true</optional>
</dependency>
Use case 3 reference to a full explanation in the description
There is also the description tag which could be used to hold more details
<dependency comment="See note 2 in description tag.”>
I’m not sure I’m seeing a difference between UC 2 & 3. Unless you mean
something more like this for UC 3:
<dependency comment_ref=“note2”> <!— or some XPath expression —>
...
<description comment_refid=“note2” comment=“This version doesn’t work for
the following reasons:….”>
I was thinking that the description might be <description>Note 1: Please
put all dependency versions in Parent, Note 2:FOP required for PDF
output</description>
IDE's could show comment attributes on tags in the POM editor or in XML
outline views.
It seems to be a lot more flexible than adding comment tags and probably
less intrusive to existing plug-ins.
I think comment tags should still be included. Inline is great for short
descriptions, but nothing really beats having a tag element that doesn’t
require a lot of XML escaping like an attribute would need.
- Jim
You are looking for a lot more machine processing that I was thinking.
I was just considering comments as a way to tell people about the choices
made.
Actually I wasn’t looking for that - just some clarity, as I didn’t fully
understand the deltas within one of your use cases. So was just posing a
confirming solution. :-) I actually dis-like using references as I
proposed - they are a pain to follow without tooling IMO. I would rather
opt to have “embedded” javadoc annotations (@see, @link, @todo, etc) within
the comment text for folks who choose to go that route.
One should never discount the need to machine process these. Consider and
IDE or document generation at the very least. IMO, anytime you have an
opportunity to structure a vocabulary to make it machine usable - one
should choose to make it machine usable to support any future automation.
Your XML escaping note is a good point.
The IDE will pick up invalid text so it should not be hard to avoid but
for people without a good IDE, they will get an error. It should only
happen once to each person editing a pom and POMs are not edited a lot in
most projects.
I work with varying degrees of IDE’s daily ranging from full blown
IntelliJ Ultimate down to a text editor. I tend to lean more on the
expectation that the IDE is feature limited; considering about 85% of the
time - I’m using a web browser to review POM’s - and I wouldn’t think I’m
alone in that categorization. Less reliance on an IDE is important.
Can you give a comment tag solution for each of the use cases.
I think what you provided is sufficient for examples, however for a more
globally portable solution, I would seriously consider using a namespace.
From there you could have a more targeted solution:
<project xmlns:cmt=“http://maven.apache.org/comments/1.0.0”>
…
<version cmt:note=“Can’t use version XZY @see(http://example.com/foo-123
)”>
<dependency>
<cmt:note>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec et
vestibulum odio, at porttitor nunc. Donec pulvinar erat quis accumsan
interdum. Nunc at viverra nunc. Mauris purus ipsum, aliquam vitae nisi
eget, faucibus auctor leo. Duis ipsum leo, viverra eleifend viverra in,
tristique vitae tortor. Interdum et malesuada fames ac ante ipsum primis in
faucibus. Suspendisse tempus nisl dui, at rutrum massa porta id.
Suspendisse ultricies est vel pretium egestas. In orci ipsum, vehicula non
accumsan quis, pellentesque ac ipsum. Maecenas maximus ornare tempus. Fusce
libero ligula, tempor mattis pretium et, consectetur ut sapien. Aliquam
rhoncus lorem erat. Nullam et.
</cmt:note>
</dependency>
Are you proposing that comment tags be allowed inside all tags or just
some.
I would suggest comment attributes on all elements.
I would vote for a comment element to be a child of any tag and a comment
attribute be available on all elements. However when considering a more
global solution, I would think adding a specific namespace for comments
makes a whole lot more sense and would be a more portable solution and
avoid collisions with existing plug-ins. IMO it’s easier to update base
parsers to disregard elements from foreign namespaces than to hope to avoid
collisions with existing plug-ins. However that’s a gut feeling without
doing any investigation as to what the scope of impact a change like that
would really mean. If it really isn't a huge problem to just add comments
to the POM namespace, that would be my #1 choice.
--
Ron Wheeler
President
Artifact Software Inc
email: [email protected]
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
