search

oasp / oasp4j

The Open Application Standard Platform for Java
Apache License 2.0
60 stars 303 forks source link

restructure modules/starters #611

Closed hohwille closed 5 years ago

hohwille commented 6 years ago

In #589 @maybeec suggested to restructure the starters to make the modules folder somewhat more clean. https://github.com/oasp/oasp4j/tree/develop/modules

Possibilities are:

1:
modules
├── basic
├── batch
├── beanmapping
├── configuration
├── cxf-client-rest
├── ...
└── web
starters
├── starter-cxf-client-rest
├── ...
└── starter-cxf-server

2: 
modules
├── basic
├── batch
├── beanmapping
├── configuration
├── cxf
|   ├── client
|   |     ├── rest
|   |     └── soap
|   └── server
|         ├── rest
|         └── soap
├── starters
|   └── cxf
|       ├── client
|       |     ├── rest
|       |     └── soap
|       └── server
|             ├── rest
|             └── soap
├── ...
└── web

3: 
modules
├── basic
├── batch
├── beanmapping
├── configuration
├── cxf
|   ├── client
|   |     ├── rest
|   |     └── soap
|   └── server
|         ├── rest
|         └── soap
├── ...
└── web
starters
├── starter-cxf-client-rest
├── ...
└── starter-cxf-server
maybeec commented 6 years ago

I would go for the flattened approach. I observed, that for initial code navigation for newcomers it is simpler to understand as you get all information at hand on the first view. If you have an hierarchical structure, you have to navigate the folders to get an understanding about the modules. Moreover, it is less overhead for maven :) May be also an issue in future having a large bunch of starter projects in eclipse ;)

amarinso commented 6 years ago

For starters I find easier as @maybeec says to find them all flattened

But strictly for modules, I would prefer the hierarchical approach, modules are more nicely "encapsulated" and you can see the general contents and not get lost into too many details

So... that will be my option number 3 :-)

hohwille commented 6 years ago

I have updated my initial text accordingly and added 3. So we all agree that we vote against 2. fine. Now we simply have to decide if modules should be flat (1) or structured (3). @maybeec any thoughts? BTW: Maven overhead is not required for directory structure. There is absolutely no necessity to added intermediate module POMs if they are considered overhead. I am quite open for both decisions however IMHO 1. is more symmetric/consistent than 3.

hohwille commented 6 years ago

For the groupIds I got feedback from @maybeec:

We already agreed on io.oasp.java.modules, io.oasp.java.samples, io.oasp.java.templates so we should distinguish starters as well as they provide added values to modules.

http://repo1.maven.org/maven2/io/oasp/java/ So therefore I would drop my concerns about the different groupIds. Then let us already confirm that the starters will all live in the groupId io.oasp.java.starters (as already done in #612) and include that change in a PR solving this issue.

For the artifactId I recommended oasp4j-starter-xyz (following the official conventions as by example spring-boot-starter-jdbc): https://www.yammer.com/capgemini.com/#/Threads/show?threadId=929127660 However https://github.com/oasp/oasp4j/pull/612/ uses oasp4j-xyz-starter as artifactId. We should asap finalize an "official" agreement for one of both namings and then align the code to use only that schema consistently. Also we should add such decisions to our docs. Maybe here: https://github.com/oasp-forge/oasp4j-wiki/wiki/oasp-code-contributions

hohwille commented 6 years ago

@sjimenez77 merged my PR to "fix" the starters accordingly. Currently we therefore have solution 1. in place. We had some proposing voices for solution 3. If we agree on that we would also need a PR for that (that could also help to boost the vote as them people could compare both approaches better). BTW: According to our roadmap - as we are using flatten plugin, this will have no effect on the release. Therefore we could also take some time to proceed with this. It is just a "development view" that changes here.

hohwille commented 6 years ago

I tried to start with a PR for 3. However, I was facing some general issues and considerations:

Therefore I would not vote for solution 3. Also we should probably think beyond and introduce a structure that gives orientation if we have even many more modules in the future. The most natural separation on top-level should IMHO be our layering:

This would not interfere so far and could already be a first step to restructure. After that we can then still think about creating subfolders like jpa and cxf as a next step and still have to solve the above issues. But maybe already the first step (layer separation) would already be sufficient until we do the merge and rebranding that is outstanding anyways and within that we can then also change artifactIds as with this step we IMHO need a "upgrade-support-tool" anyhow (that can refactor all pom.xml and *.java files of a project with a simple mapping of old to new names/Ids that we provide for the upgrade.

maybeec commented 6 years ago

Lets recover the initial idea: separating starters from modules as they serve a completely different purpose. From my perspective, we should not start to be too academic here and just have a flat representation of modules and starters but both seperated. This will even comply to the general idea of parent poms to provided shared dependencies (esp. for starters). The initial idea to restructure everything was good, but turned out to be not easily feasiable and having a log of overhead even as we introduce a lot of parent poms, which may not be necessary from a code sharing perspective at all.

hohwille commented 5 years ago

So according to our current code-base I can consider this issue as done. If there are concrete suggestions for further improvements then file a new issue.