CHANGELOG.md is outdated about graal HOT 8 CLOSED

The new policy includes that every API change must be documented in the change log in prosaic form before getting integrated. Changelog descriptions for older versions where added.

from graal.

I plan to remove the manually written changelog and replace it by automatically generated one that is included in the documentation. NetBeans is using arch.xml and apichanges.xml for that. I'd rather replace that with annotations processed by an annotation processor. But I need to write that tool first.

from graal.

Manually written, it can give short summary/overview about what happened in a release, without going into too much detail. Feels better than having to dig out announcement emails (which served a similar purpose) from the mailing list archive.

from graal.

First of all we need to mark all elements in the API with the version they were introduced at. Here is my current diff: TruffleAddSinceTag.diff

It assigns version 0.8 to all elements. I have chosen 0.8 as it is the old version I know; probably nobody cares about older versions anymore and it is relatively easy to find out newer elements and change their version of 0.9, 0.10, 0.11.

I plan to apply the @since tag change tomorrow.

from graal.

I agree that a manually-written changelog is much more useful than an automated generated list, maybe @since is overkill here?

from graal.

• @since tag is a nice way to find out whether an element is or isn't intended to be public.
  • if we had this check, error #82 wouldn't have to be fixed now
• @since tag provides well-understood information about origin of particular API element
  • Java core API is using it and people know what it means
  • By looking at latest Javadoc one can understand evolution history of the API

from graal.

The desirable rule to achieve in the Truffle repository should be: "Every element in the API needs to have Javadoc with @since tag":

• Obviously having elements in the API without Javadoc is wrong
• with Javadoc being there, the additional requirement to add one more line @since X.Y seems easy

from graal.

I have added prosaic description of what happened on 0.13 version into the https://github.com/graalvm/truffle/blob/truffle-0.13/CHANGELOG.md based on the sigtest and @SInCE tag information.

from graal.