Naming convention for ported GWT modules

[Mincong Huang]

Hi,

I'd like to have a clarification about the naming convention for ported GWT modules. Because I'm porting the module `gwt-safecss` and `gwt-animation`. When I go to Vertispan repository [1], the available modules do not use the same rule for the group ID and artifact ID. This is a pain when you reference them as dependencies. Here're 5 rules that I found.

Rule 1:

Use "org.gwtproject" + module name as group id; module name with "gwt-" prefix as artifact id. This rule is used by `gwt-http`:

    GROUP_ID:    org.gwtproject.$MODULE

    ARTIFACT_ID: gwt-$MODULE

Rule 2:

Use "org.gwtproject" + module name as group id; module name without "gwt-" prefix as artifact id. This rule is used by `gwt-event`, `gwt-place`, `gwt-safehtml`, `gwt-storage`, `gwt-timer`:

    GROUP_ID:    org.gwtproject.$MODULE

    ARTIFACT_ID: $MODULE

Rule 3:

Use "org.gwtproject" as group id; module name with "gwt-" prefix as artifact id. This rule is used by `gwt-xhr`:

    GROUP_ID:    org.gwtproject

    ARTIFACT_ID: gwt-$MODULE

Rule 4:

Use "org.gwtproject" as group id; module name without "gwt-" prefix as artifact id. This rule is used by `gwt-json`, `gwt-typedarrays`, `gwt-xml`, `gwt-xhr`:

    GROUP_ID:    org.gwtproject

    ARTIFACT_ID: $MODULE

Rule 5:

Other rules: `gwt-window`, `gwt-history`.

I suggest we apply rule 4 to all the modules. It means always using "org.gwtproject` as group id, and use `gwt-` + module name as artifact id. There're several benefits. It helps people to find all the artifacts via the same group id. It also keeps consistency for the generated JAR files: each of them contains a "gwt-" prefix, thus they are GWT artifacts.

Cheers,

Mincong Huang

[1]: https://repo.vertispan.com/gwt-snapshot/

[Thomas Broyer]

On Saturday, March 24, 2018 at 10:30:10 AM UTC+1, Mincong Huang wrote:

Hi,

I'd like to have a clarification about the naming convention for ported GWT modules. Because I'm porting the module `gwt-safecss` and `gwt-animation`. When I go to Vertispan repository [1], the available modules do not use the same rule for the group ID and artifact ID. This is a pain when you reference them as dependencies. Here're 5 rules that I found.

This is a subject we briefly discussed last week in our steering committee meeting, acknowledging the issue.

 

Rule 1:

Use "org.gwtproject" + module name as group id; module name with "gwt-" prefix as artifact id. This rule is used by `gwt-http`:

    GROUP_ID:    org.gwtproject.$MODULE

    ARTIFACT_ID: gwt-$MODULE

Rule 2:

Use "org.gwtproject" + module name as group id; module name without "gwt-" prefix as artifact id. This rule is used by `gwt-event`, `gwt-place`, `gwt-safehtml`, `gwt-storage`, `gwt-timer`:

    GROUP_ID:    org.gwtproject.$MODULE

    ARTIFACT_ID: $MODULE

gwt-events actually falls in rule 1.

 

Rule 3:

Use "org.gwtproject" as group id; module name with "gwt-" prefix as artifact id. This rule is used by `gwt-xhr`:

    GROUP_ID:    org.gwtproject

    ARTIFACT_ID: gwt-$MODULE

Rule 4:

Use "org.gwtproject" as group id; module name without "gwt-" prefix as artifact id. This rule is used by `gwt-json`, `gwt-typedarrays`, `gwt-xml`, `gwt-xhr`:

    GROUP_ID:    org.gwtproject

    ARTIFACT_ID: $MODULE

Rule 5:

Other rules: `gwt-window`, `gwt-history`.

Those fall (almost) in rule 1, with an additional "user" in groupId: org.gwtproject.user.$MODULE:gwt-$MODULE

 

I suggest we apply rule 4 to all the modules. It means always using "org.gwtproject` as group id, and use `gwt-` + module name as artifact id. There're several benefits. It helps people to find all the artifacts via the same group id. It also keeps consistency for the generated JAR files: each of them contains a "gwt-" prefix, thus they are GWT artifacts.

My rule of thumb was to use a "subgroup" of "org.gwtproject" when there was several artifacts, as can be seen in gwt-events and gwt-places. For other cases, I'm always hesitating between bare "org.gwtproject" and a subgroup.

Fwiw, we settled on always using a subgroup (IIRC; Colin, please correct me if I misremember). This means rule 1 or 2 rather than 3 or 4. And I would tend to agree with using a "gwt-" prefix for artifact IDs, though if you read the artifact name as being groupId+artifactId, then that prefix would be redundant with the "org.gwtproject" prefix of the groupId.

Compare, for example

• org.gwtproject:http vs org.gwtproject:gwt-http vs org.gwtproject.http:http vs org.gwtproject.http:gwt-http
• org.gwtproject:logical-event vs org.gwtproject:gwt-logical-event vs org.gwtproject.event:logical vs org.gwtproject.event:logical-event vs org.gwtproject.event.gwt-logical-event (this goes with "event" and "compat" artifacts)

[Mincong Huang]

On Sat, Mar 24, 2018 at 12:27 PM, Thomas Broyer <t.br...@gmail.com> wrote:

On Saturday, March 24, 2018 at 10:30:10 AM UTC+1, Mincong Huang wrote:

Hi,

I'd like to have a clarification about the naming convention for ported GWT modules. Because I'm porting the module `gwt-safecss` and `gwt-animation`. When I go to Vertispan repository [1], the available modules do not use the same rule for the group ID and artifact ID. This is a pain when you reference them as dependencies. Here're 5 rules that I found.

This is a subject we briefly discussed last week in our steering committee meeting, acknowledging the issue.

 

Rule 1:

Use "org.gwtproject" + module name as group id; module name with "gwt-" prefix as artifact id. This rule is used by `gwt-http`:

    GROUP_ID:    org.gwtproject.$MODULE

    ARTIFACT_ID: gwt-$MODULE

Rule 2:

Use "org.gwtproject" + module name as group id; module name without "gwt-" prefix as artifact id. This rule is used by `gwt-event`, `gwt-place`, `gwt-safehtml`, `gwt-storage`, `gwt-timer`:

    GROUP_ID:    org.gwtproject.$MODULE

    ARTIFACT_ID: $MODULE

gwt-events actually falls in rule 1.

Yes, indeed. You're right.

 

 

Rule 3:

Use "org.gwtproject" as group id; module name with "gwt-" prefix as artifact id. This rule is used by `gwt-xhr`:

    GROUP_ID:    org.gwtproject

    ARTIFACT_ID: gwt-$MODULE

Rule 4:

Use "org.gwtproject" as group id; module name without "gwt-" prefix as artifact id. This rule is used by `gwt-json`, `gwt-typedarrays`, `gwt-xml`, `gwt-xhr`:

    GROUP_ID:    org.gwtproject

    ARTIFACT_ID: $MODULE

Rule 5:

Other rules: `gwt-window`, `gwt-history`.

Those fall (almost) in rule 1, with an additional "user" in groupId: org.gwtproject.user.$MODULE:gwt-$MODULE

 

I suggest we apply rule 4 to all the modules. It means always using "org.gwtproject` as group id, and use `gwt-` + module name as artifact id. There're several benefits. It helps people to find all the artifacts via the same group id. It also keeps consistency for the generated JAR files: each of them contains a "gwt-" prefix, thus they are GWT artifacts.

My rule of thumb was to use a "subgroup" of "org.gwtproject" when there was several artifacts, as can be seen in gwt-events and gwt-places. For other cases, I'm always hesitating between bare "org.gwtproject" and a subgroup.

Fwiw, we settled on always using a subgroup (IIRC; Colin, please correct me if I misremember). This means rule 1 or 2 rather than 3 or 4. And I would tend to agree with using a "gwt-" prefix for artifact IDs, though if you read the artifact name as being groupId+artifactId, then that prefix would be redundant with the "org.gwtproject" prefix of the groupId.

Using the same group ID for every artifact is easier for searching. For instance, you can use query `g:"com.google.gwt"` to search all the GWT artifacts in Maven central repository. You must do a wildcard search if group ID contain a subgroup. However, I understand that a sub group contains multiple modules, so rule 1 and 2 have their interest. Another way could be:

Rule 6:

Using "org.gwtproject" as group id; "gwt-" prefix with optional subgroup and module name as artifact ID:

    GROUP_ID:     org.gwtproject

    ARTIFACT_ID:  gwt-$SUBGP-$MODULE

Therefore, subgroup becomes the first order in artifact listing. And the "gwt-" prefix is useful for identifying GWT jar—an counter-example is `json-1.0-20180116.161204-1.jar`, without the group ID, I can't tell it belong to GWT.

Compare, for example

• org.gwtproject:http vs org.gwtproject:gwt-http vs org.gwtproject.http:http vs org.gwtproject.http:gwt-http
• org.gwtproject:logical-event vs org.gwtproject:gwt-logical-event vs org.gwtproject.event:logical vs org.gwtproject.event:logical-event vs org.gwtproject.event.gwt-logical-event (this goes with "event" and "compat" artifacts)

Thanks for these examples. I formatted it for those who want a vertical comparison.

org.gwtproject:http

org.gwtproject:gwt-http

org.gwtproject.http:http

org.gwtproject.http:gwt-http

org.gwtproject:logical-event

org.gwtproject:gwt-logical-event

org.gwtproject.event:logical

org.gwtproject.event:logical-event

org.gwtproject.event.gwt-logical-event

---

org.gwtproject:gwt-event-logical (rule 6)

There're two other questions:

- Why not using `org.gwt` instead of `org.gwtproject`?

- We're discussing sub groups here. But all the sub groups are under gwt-user. What about gwt-dev and other parts? Is `user` and `dev` are considered as subgroup? (Thus Rule 5 makes sens)

Mincong

--
You received this message because you are subscribed to the Google Groups "GWT Contributors" group.
To unsubscribe from this group and stop receiving emails from it, send an email to google-web-toolkit-contributors+unsubscribe@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/google-web-toolkit-contributors/ac6913ab-7240-4fcb-8d5b-4a48085089b6%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Ahmad Bawaneh]

OK then, this means that gwt-timer should use org.gtwproject as group id and gwt-timer as artifact id.

[Colin Alworth]

"gwt.org" is not available - it refers to a hiking trail.

My suggestion is org.gwtproject.$module:gwt-$module.

Cons:
 - Redundant appearance of $module, and of "gwt"

Pros:
 - Multi-module maven projects all have the same groupid, instead of requiring that the gwt-event project all be under org.gwtproject, or inconsistently using org.gwtproject.$module for multi-module projects or org.gwtproject for single-module projects. Very reasonably we might have projects switch between these states (adding examples, etc), so we should be consistent between types of projects
 - The "gwt-" prefix makes it clear by looking at just the jar's name (in your IDE's maven dependency jar list, etc) where an artifact comes from
 - Room is left at the top for more modules, without assuming that all org.gwtproject:* modules are for the client (org.gwtproject.tools, etc)


While that's my preferred option, my only strong opinion here is that we plan for future maintainability - the need to change structure and add additional modules to any one project (ideally maintaining coordinates of a dependency that is in use), and consistency across modules.

[Jens]

What about

org.gwtproject.sdk:gwt-$module and org.gwtproject.sdk:gwt-$module-processor (keep the optionally APT module flat within org.gwtproject.sdk group Id)

org.gwtproject.examples:$lots-of-example-apps-using-any-gwt-module-combinations

org.gwtproject.site:...

org.gwtproject.tools:...

org.gwtproject.incubator:...

I can only hardly see GWT modules having more than three sub modules (main module, example module, APT processor module). Is there a reason why gwt-events has multiple modules? Haven't looked into the code yet. Given GWT modules are usually focused I would try to avoid multi module projects for them.

I always hesitate to create a multi module project just to bundle some example module because the main module name either becomes "core" / "lib" or something like that or repeats part of the group ID, e.g. org.gwtproject.sdk.dom:gwt-dom and org.gwtproject.sdk.dom:example (btw ...:gwt-example would somehow sound silly here actually). So I usually prefer a single multi-module example project that contains multiple examples. I think this also resembles better what examples are: they use some product to show its capabilities, but it does not define the product itself. 

-- J.

[Thomas Broyer]

Fwiw, I can see zero reason why examples would be published to a Maven repo.

Wrt events, each corresponds to a different GWT module: c.g.g.event+c.g.w.b.event, c.g.g.event.logical, and some adapters for when you need to mix org.gwtproject.event with c.g.g.event or c.g.w.b.event. We could also add DOM events if needed/requested (fwiw, the only reason I ported over logical events is because Window and History use them)

[Ahmad Bawaneh]

Hi

i am working on date pickers for domino-ui, mean while i found that in order to support different locales in the date picker i need the DateTimeFormat information for each locale, gwt in the other hand has a decent support for datetime format informtion, so instead of adding my own implementation and after a small discussion with colin i decided to use gwt DatetimeFormat implementation, but to avoid adding dependency on gwt-user i decided to work in a partial porting of the gwt datetime formats, i am modifing the cldr-import tool to generate the sources into there own module/jar with the new package name org.gwtproject.X to make sure that later they can be used with the rest of the i18n porting, also i am migrating the gwt cldr-importer from ant to gradle, the new one will reduce the manual steps to generate new cldr classes, so instead of checkout, build, copy, import, it will be a single commad to acheive it all. i will make the repository avialble for review and feedback on github very soon when i am done.

my question here is 

for the new cldr data generator i should use
groupId : org.gwtproject.tools, artifactId : gwt-cldr-importer does this look right?

On Saturday, March 24, 2018 at 11:30:10 AM UTC+2, Mincong Huang wrote:

[Thomas Broyer]

On Friday, April 6, 2018 at 6:16:50 PM UTC+2, Ahmad Bawaneh wrote:

Hi

i am working on date pickers for domino-ui, mean while i found that in order to support different locales in the date picker i need the DateTimeFormat information for each locale, gwt in the other hand has a decent support for datetime format informtion, so instead of adding my own implementation and after a small discussion with colin i decided to use gwt DatetimeFormat implementation, but to avoid adding dependency on gwt-user i decided to work in a partial porting of the gwt datetime formats, i am modifing the cldr-import tool to generate the sources into there own module/jar with the new package name org.gwtproject.X to make sure that later they can be used with the rest of the i18n porting, also i am migrating the gwt cldr-importer from ant to gradle, the new one will reduce the manual steps to generate new cldr classes, so instead of checkout, build, copy, import, it will be a single commad to acheive it all. i will make the repository avialble for review and feedback on github very soon when i am done.

my question here is 

for the new cldr data generator i should use
groupId : org.gwtproject.tools, artifactId : gwt-cldr-importer does this look right?

Does that really matter? I mean, do we really want/need to publish that artifact? Isn't it only needed to generate the actual module that everyone will use?

Otherwise, I'd go with the same org.gwtproject.X as the generated module.

[Ahmad Bawaneh]

Yes, you are right, now both the importer and the cldr repository are available on github 

The importer :

https://github.com/vegegoku/gwt-cldr-importer

The gwt-cldr

https://github.com/vegegoku/gwt-i18n-cldr

the cldr uses the org.gwtproject.i18n groupId and gwt-cldr as artifactId

Your kind review is really appreciated specially for the grade build scripts as i am new to gradle.

Thanks

[Jens]

Fwiw, I can see zero reason why examples would be published to a Maven repo.

Well right, although quite a lot projects do so. But maybe just because examples are part of a multi module project and they just deploy everything to maven central. That would even be a stronger argument to move examples out of each project into a dedicated org.gwtproject.examples namespace. Otherwise, when following maven conventions you end up with multi module project coordinates but only   deploy a single artifact. Then you would end up again with the repetitive org.gwtproject.xx.<modulename>:gwt-<modulename> pattern.

-- J.

[Thomas Broyer]

On Saturday, April 7, 2018 at 6:48:53 PM UTC+2, Jens wrote:

Fwiw, I can see zero reason why examples would be published to a Maven repo.

Well right, although quite a lot projects do so. But maybe just because examples are part of a multi module project and they just deploy everything to maven central. That would even be a stronger argument to move examples out of each project into a dedicated org.gwtproject.examples namespace. Otherwise, when following maven conventions you end up with multi module project coordinates but only   deploy a single artifact. Then you would end up again with the repetitive org.gwtproject.xx.<modulename>:gwt-<modulename> pattern.

What matters really is what you deploy, otherwise groupId/artifactId/version are mostly just an annoyance (one more reason I like Gradle better, those are entirely optional there).

For example, that a submodule has a <parent> (in many cases being the aggregator module) is not a "convention", it's a cargo cult.

Anyway, this is something we can probably "control" as a community for org.gwtproject artifacts/projects.