Improve JPMS specifications

[Robert Scholte]

In order to get more consensus within the EG I like to reach out regarding
to the specification descriptions in general.

# When to use Jigsaw

You could in some way say that Jigsaw introduces new rules during the game.
In the original game, having split packages could be a wise decision, just
like having an interface and its default implementation within the same  
package.
Rearranging classes over jars could result in duplicate classes or missing  
classes
after the dependency resolution for the artifacts on the  
classpath/modulepath.
It is likely that projects cannot move towards modularization and the  
message should
be that this is fine. The advice should be that *new* projects should try  
to
follow these new rules and depending on the state of its dependencies  
choose
when to add module descriptors.

With this assumption I think we should go for the more strict, though  
still usable
solution right now until it is proven that things are too strict. Up until  
now the
concerns are mainly based on the way of development done now  without  
restrictions
as they are defined by Jigsaw and the experience we have with it.

It must be made clear that it is not always possible to switch to a modular
project due to changed rules, which is fine. However, new next generation
Java applications should be advised to start as modular Java project or at
least keep in mind the new specifications.

# Provide explicit descriptions regarding applications and libraries

The way applications and libraries are developed are quite different, just  
like the
advice how to apply the modular system. It would help readers a lot if the  
specs mention these concepts separately.

e.g. public libraries should only refer to modular jars and to automodules  
with a Automatic-Module-Name attribute in the MANIFEST file. In other  
cases don't add a module descriptor.
The attribute Automatic-Module-Name should *only* be used if the Java  
project is JPMS-ready but can't provide a module descriptor yet.
For applications it doesn't make sense to add the Automatic-Module-Name to  
the MANIFEST file.
For application it doesn't make sense to export packages.

# Avoid the term "migration"

Migration suggest there's a path to slowly adopt Jigsaw functionality, but
IMHO there's not. You simply choose between using or not using.
(Public) Library development will still need the bottom up approach before  
being able to become modular.
Application development can make use automodules.

So the returning term "easy of migration" doesn't sounds correct anymore  
to me. Auto modules are there to make your application compile/run with a  
module descriptor.
Libraries still follow the bottom up principal and require additional  
action from their dependency maintainers, either by providing a jar with a  
module descriptor or a Automatic-Module-Name.

These are some of the topics I'd like to see improved

thanks,
Robert