3.3.3 release plan

[Brent Easton]

That's fine. I prefer the deployed code to be the same as the original source anyway.

Do we need a custom tag? Couldn't it just check the since attribute on the @Deprecated tags?

[Flint1b]

I didn't even know the @Deprecated tag had a "since" attribute, I've just checked and it is meant to contain a version number not a date, but you are right maybe we could (mis-)use that. The more interesting question is then, how do we evaluate the contents of this "since" attribute as a date, what would it take to evaluate this during the build and print out a warning into the build log.

[Brent Easton]

Surely there must be Maven plugins that look at the Deprecated since attribute? Though they probably compare it to the current version number in Maven. If we could the get source we could roll our own.

[Flint1b]

It's even easier than I thought, there is no need for a special maven plugin, we just need our annotation, an annotation processor, and tell the compiler to use this processor. I made an experimental PR, have a look: https://github.com/vassalengine/vassal/pull/165

We probably could use the regular @Deprecated annotation for this, but I see two reasons why it's better to write our own: a) we would be misusing the "since" field and put differently formatted information in it than it expects, possibly even get problems with the compiler due to that, and b) annotation processing has this thing where annotations are processed kind of like UI events and a processor can "consume" an annotation thereby hiding it from further processors, it's probably safer if we don't risk consuming the @Deprecated annotation and hiding it from the compiler.

[Brent Easton]

Ok, that's looking really promising. I split this Depraction issue into 2 issues on the tracker. 13243 for displaying the dialogs and 13244 for the maven plugin, which looks like it will be covered instead by this.

The only problem I see with not using @Deprecated is that unless we double annotate each deprecated method with both @Deprecated and @VassalDeprecated, then the compilers, other plugins and our IDE's won't recognized these methods as Deprecated and do their usual thing. You have effectively hidden all the Deprecations from the compiler anyway.

I don't see a problem with using the date like that as a version number. It is not defined what format a version number must be. There's not nothing to say it can be nnnn-nn-nn instead of nnnn.nn.nn. I believe it's only documentary anyway since the compiler has nothing to compare it to.

Give it a try with @Deprecated and see what happens, surely there should be a way to stop it consuming them. I think that would be preferable if we can get away with just the single @Deprecated.

I was thinking maybe break the build if it has been more than a year or since is invalid or missing, show a warning if more than, say 10 months, otherwise no message.

[Flint1b]

The format of the "since" is defined:

Code: Select all

    /**
     * Returns the version in which the annotated element became deprecated.
     * The version string is in the same format and namespace as the value of
     * the {@code @since} javadoc tag. The default value is the empty
     * string.
     *
     * @return the version string
     * @since 9
     */
    String since() default "";


And the custom annotation is not meant to be used instead of the regular @Deprecated, it has nothing to do with @Deprecated at all. They can be used side by side.

[Brent Easton]

es, and if you look up the definition of the @since Javadoc tag (which was surprisingly difficult to find), it says

Code: Select all

Adds a Since heading with the specified since-text value to the generated documentation. The text has no special internal structure.

So, you can basically put whatever you like in it, nothing will ever complain. The examples always show a number like 9 or 1.2, but they are only examples. The original usage was '@since JDK1.1' which included characters before it started to be used for non JDK software.

And the custom annotation is not meant to be used instead of the regular @Deprecated, it has nothing to do with @Deprecated at all. They can be used side by side.

Yes, I understand that, but since every single custom annotation will have to also have an @Deprecated annotation that has a perfectly useful @since attribute, then @Deprecated by itself fully supports the functionality we want.

[Flint1b]

Well we can use the @Deprecated just as well. My code was just an experiment anyways. We can throw away the custom annotation, adjust the annotation processor to process the @Deprecated, adjust the logic to print warnings after 8 months and error after a year. Just have to be careful to not return "true" from the process() method, this is what consumes the annotation if I understood correctly.

[Brent Easton]

Sounds good, I think it will save on meaningless busy work. I had a play with your DeprecationProcessor, pretty cool. I played around with it and got it sort of working with @Deprecated. Then did something, I do not know what and it doesn't seem to run at all any more. I'll leave that one to you.

I thought about the Deprecated fields. They seem to be mostly either not used by any Vassal code anymore, or are closely tied to and used by methods that have also been Deprecated. I think we just add the since= to these as well and delete them after the year.