[GREENFOOT-152] Improve the handling of API version and warnings
The API versions gets upgraded too often \- and the user often gets unnecessary warning messages about the API upgrade.
We will probably need several kinds of version number to distinguish different changes. The changes that can happen are listed in the next section and after that we list the possible actions to be taken.
h1. Types of change in version numbers When a new version of Greenfoot is released the following changes can happen that affects the API version number.
No Change (Greenfoot Update only):: bq. Nothing has changed in relation to the API version.
Internal implementation of World/Actor has changed:: bq. Changes has happened internally in the implementation of the World and/or Actor. None of these changes must be visible to the user in any way. Changes could for instance be refactorings. If changes modifies the exposed methods by changing their definition, documentation or functionality they should NOT be included here.
Non-breaking changes to the exposed API:: bq. Changes has been made to the API (World, Actor, GreenfootImage, Greenfoot) that is visible to the user but is unlikely to actually break anything. This could be changes to the documentation or addition of methods and/or classes. Adding these could lead to breaking in some rare cases: if the user has already implemented classes or methods with the same signature. But these cases are rare enough that we don't care about them.
Breaking API changes:: bq. This includes changes that can break some scenarios. This could be changes to functionality of existing methods, changes to method signatures, renaming methods, deleting methods, etc.
h1. Actions that can be taken
No action:: bq. Nothing happens
Copy Actor and World to scenario:: bq. The Actor and World is copied to the scenario directory. Should not require a recompile of the user's classes.
Change user visible API version:: bq. The API version that the user can see is changed. This is the version number that can be seen in the javadoc for the API. Should require a recompile of the user's classes, by striping the user classes.
Warning shown to the user:: bq. A warning is shown to the user that things might break. Recompile required.
h1. Relations between changes and actions We now have 4 types of changes and 4 actions that we want to match. This is represented in the table below
| Change \ Action | None | Copy | User API# | Warning | | No Change | X | | | | | Intenal only | X | X | | | | Non breaking | X | X | X | | | Breaking | X | X | X | X |
h1. Version numbers
We need to be able to distinguish (from the code) the 4 different changes. This means that we essentially need a version number for each of the four types of changes. This means that we need 4 different version numbers where we currently only have 2.
| Versions | Examples | Name | | New Greenfoot release | 1.4.6 | Greenfoot Version | | Internal API changes | 31.4.8 | Internal Version | | Non breaking API changes | 31.4 | API Version (used in JavaDoc for API) | | Breaking API changes | 31 | Breaking Version |
The API Version is the version number exposed to the user through the javadoc for the API. We might need to add an extra dummy digit to this number so that old versions of Greenfoot wont die when trying to read this number (because old version will expect 3 digits).
Issue metadata
- Issue type: Bug
- Priority: Medium
- Fix versions: 1.4.6