then it is just a matter of sending the output of the last command to an observer mailing list, so humans can decide whether the change is intended or not.

then it is just a matter of sending the output of the last command to an observer mailing list, so humans can decide whether the change is intended or not.

<source lang="bash">

<source lang="bash">

$ mx sigtest --generate

$ mx sigtest --generate

</source>

</source>

==== Notification of Daily Changes ====

==== Notification of Daily Changes ====

In addition to catching [[BackwardCompatible|incompatible]] changes, it is useful to track compatible ones as well Some of the [[API]] changes happen by an accident and when they aren't noticed in time, they may become part of a release. But then they have to stay (as they are like [[star]]s) regardless how bad they are. Nobody wants to maintain erroneous code or [[API]], so it is better to catch such changes as soon as possible and revert them before they propagate to a release.

In addition to catching [[BackwardCompatible|incompatible]] changes, it is useful to track [[BackwardCompatible|compatible ones]] as well.

 

Some of the [[API]] changes happen by an accident and when they aren't noticed in time, they may become part of a release. But then they have to stay (as they are like [[star]]s) regardless how bad they are. Nobody wants to maintain erroneous code or [[API]], so it is better to catch such changes as soon as possible and revert them before they propagate to a release.

Having a [[Hudson]] job to watch daily compatible changes and notify us about them is the best way to prevent accidental [[API]] changes. The job shall have two parts: generate new snapshot of today's [[API]]s:

Having a [[Hudson]] job to watch daily compatible changes and notify us about them is the best way to prevent accidental [[API]] changes. The job shall have two parts: generate new snapshot of today's [[API]]s:

==== Notification of Daily Changes ====

==== Notification of Daily Changes ====

[[TBD]]: [[I]] will set a [[Hudson]] job to watch daily compatible changes and notify us about them - so we can prevent accidental [[API]] changes.

In addition to catching [[BackwardCompatible|incompatible]] changes, it is useful to track compatible ones as well Some of the [[API]] changes happen by an accident and when they aren't noticed in time, they may become part of a release. But then they have to stay (as they are like [[star]]s) regardless how bad they are. Nobody wants to maintain erroneous code or [[API]], so it is better to catch such changes as soon as possible and revert them before they propagate to a release.

 

Having a [[Hudson]] job to watch daily compatible changes and notify us about them is the best way to prevent accidental [[API]] changes. The job shall have two parts: generate new snapshot of today's [[API]]s:

 

 

 

 

then it is just a matter of sending the output of the last command to an observer mailing list, so humans can decide whether the change is intended or not.

* Adjusting to binary incompatible change of (on)returnExceptional parameters [http://lafo.ssw.uni-linz.ac.at/hg/truffle/rev/7273b139fff2 7273b139fff2] - this was an intentional and agreed on change (in spite of being against the [http://lafo.ssw.uni-linz.ac.at/javadoc/truffle/latest/overview-summary.html compatibility policy])

* Adjusting to binary incompatible change of (on)returnExceptional parameters [http://lafo.ssw.uni-linz.ac.at/hg/truffle/rev/7273b139fff2 7273b139fff2] - this was an intentional and agreed on change (in spite of being against the [http://lafo.ssw.uni-linz.ac.at/javadoc/truffle/latest/overview-summary.html compatibility policy])

* And at last, there was an [[API]] [http://lafo.ssw.uni-linz.ac.at/hg/truffle/rev/23d2b5513c83 design problem] - a return type of an [[API]] visible method was not public - e.g. visible

* And at last, there was an [[API]] [http://lafo.ssw.uni-linz.ac.at/hg/truffle/rev/23d2b5513c83 design problem] - a return type of an [[API]] visible method was not public - e.g. visible

In all of these cases [[I]] manually updated the signature files to match the expected state. Then the compatibility check finally succeeded.

In all of these cases [[I]] manually updated the signature files to match the expected state. Then the compatibility check finally succeeded. Since today it will be way easier to keep [[BackwardCompatibility]] in our [[Truffle]] project!

==== Notification of Daily Changes ====

==== Notification of Daily Changes ====

[[TBD]]: [[I]] will set a [[Hudson]] job to watch daily compatible changes and notify us about them - so we can prevent accidental [[API]] changes.

[[TBD]]: [[I]] will set a [[Hudson]] job to watch daily compatible changes and notify us about them - so we can prevent accidental [[API]] changes.

Here is how such snapshot files look like: [http://lafo.ssw.uni-linz.ac.at/hg/truffle/rev/b07854a19ab4 changeset]. Of course, it turned out that not everything is perfect (how it could be! we weren't running the tests and it is so hard to reason about [[BackwardCompatibility]] without testing):

Here is how such snapshot files look like: [http://lafo.ssw.uni-linz.ac.at/hg/truffle/rev/b07854a19ab4 changeset]. Of course, it turned out that not everything is perfect (how it could be! we weren't running the tests and it is so hard to reason about [[BackwardCompatibility]] without testing):

* Removing API elements that were deprecated at the time of truffle-0.9 release from the list of required API elements: [http://lafo.ssw.uni-linz.ac.at/hg/truffle/rev/2ce4c49bc131 2ce4c49bc131] - [[Truffle]] project is still in its early phases, so according to our [http://lafo.ssw.uni-linz.ac.at/javadoc/truffle/latest/overview-summary.html compatibility policy] this is OK.

* Removing API elements that were deprecated at the time of truffle-0.9 release from the list of required API elements: [http://lafo.ssw.uni-linz.ac.at/hg/truffle/rev/2ce4c49bc131 2ce4c49bc131] - [[Truffle]] project is still in its early phases, so according to our [http://lafo.ssw.uni-linz.ac.at/javadoc/truffle/latest/overview-summary.html compatibility policy] removing deprecated elements is OK. Once we reach release 1.0, we won't do things like this.

* The check discovered a removed constructor [http://lafo.ssw.uni-linz.ac.at/hg/truffle/rev/5033b980cc68 5033b980cc68] which was clearly a bug

* The check discovered a removed constructor [http://lafo.ssw.uni-linz.ac.at/hg/truffle/rev/5033b980cc68 5033b980cc68] which was clearly a bug

* Adjusting to binary incompatible change of (on)returnExceptional parameters [http://lafo.ssw.uni-linz.ac.at/hg/truffle/rev/7273b139fff2 7273b139fff2] - this was an intentional and agreed on change (in spite of being against the [http://lafo.ssw.uni-linz.ac.at/javadoc/truffle/latest/overview-summary.html compatibility policy])

* Adjusting to binary incompatible change of (on)returnExceptional parameters [http://lafo.ssw.uni-linz.ac.at/hg/truffle/rev/7273b139fff2 7273b139fff2] - this was an intentional and agreed on change (in spite of being against the [http://lafo.ssw.uni-linz.ac.at/javadoc/truffle/latest/overview-summary.html compatibility policy])

<source lang="bash">

<source lang="bash">

$ hg up -C truffle-0.9

$ hg up -C truffle-0.9

$ mx sigtest --generate

$ mx sigtest --generate

$ hg up default

$ hg up default

$ hg up -C truffle-0.9

$ hg up -C truffle-0.9

$ mx sigtest --generate

$ mx sigtest --generate

$ hg add .

$ hg add .

$ hg ci -m "Adding API snapshots as for version truffle-0.9 and enabling their check in the gate"

$ hg ci -m "Adding API snapshots as for version truffle-0.9 and enabling their check in the gate"

# generate - which will take a snapshot of your [[API]] at a certain point of time (usually at a release time)

# generate - which will take a snapshot of your [[API]] at a certain point of time (usually at a release time)

# check - which will compare the current state of your [[API]] with the existing snapshot

# check - which will compare the current state of your [[API]] with the existing snapshot

The way to invoke these operation in [[Truffle]] repository are like:

To invoke these operations in [[Truffle]] repository use:

<source lang="bash">

<source lang="bash">

$ mx sigtest --generate

$ mx sigtest --generate

==== Integrate into Build Process ====

==== Integrate into Build Process ====

[[SignatureTests|Signature testing]] needs to be integrated into build process of your project - in case there is a violation with respect to [[BackwardCompatibility]], the build should fail. As (almost) every big project invents its own build harness, the ways to integrate differs. For example, [[NetBeans]] is using [[Ant]] based harness and thus one deals with the signature testing tool via [[Ant]] as described at [[netbeans:SignatureTest]] page.

[[SignatureTests|Signature testing]] needs to be integrated into build process of your project - in case there is a violation with respect to [[BackwardCompatibility]], the build should fail. As (almost) every big project invents its own build harness, the ways to integrate differ. For example, [[NetBeans]] is using [[Ant]] based harness and thus one deals with the signature testing tool via [[Ant]] as described at [[netbeans:SignatureTest]] page.

The [[Truffle]] project (as well as [[Graal]]) is using [[Python]] based harness. As such [[I]] had to write a bit of [[Python]] code to integrate the [[netbeans:APITest|APITest]] into it (see [https://bitbucket.org/allr/mx/src/e7fa425baca686c418ffa3cb521fa3f853a994a6/mx_sigtest.py here]). You basically need two operations:

The [[Truffle]] project (as well as [[Graal]]) is using [[Python]] based harness. As such [[I]] had to write a bit of [[Python]] code to integrate the [[netbeans:APITest|APITest]] into it (see [https://bitbucket.org/allr/mx/src/e7fa425baca686c418ffa3cb521fa3f853a994a6/mx_sigtest.py here]). You basically need two operations: