Re: [keycloak-dev] Fwd: Concept structure in the VCS?

From: "Lennart Jörelid" <lennart.jorelid(a)gmail.com&gt; To: keycloak-dev(a)lists.jboss.org Sent: Sunday, 9 August, 2015 7:00:59 PM Subject: [keycloak-dev] Fwd: Concept structure in the VCS? Ah - by mistake, I replied only to Bill. Cross-posting to the list as well. Sorry for the spam. ====== Hello there, First - I found the current screencasts massively helpful in getting started, to be honest. They are something I really have not seen in most projects, and they contributed a lot to me making sense of the Keycloak codebase and usage scenarios. Kudos. Sedond - I think it would be quite helpful to add additional modularization and also harmonize some configuration to make it more evident in how it is interpreted. Let me clarify the last bit here (I'll take themes as an example, but I believe that the same conclusion stands for other parts of the Keycloak codebase): # Import and extend definitions parent = base import = common/keycloak styles = lib/patternfly/css/patternfly.css lib/zocial/zocial.css stylesheets/login.css stylesheets/yourOwn.css 1. The documentation and examples provides something roughly similar to the above. 2. Turning the attention to the "import" parameter, one could jump to the conclusion that there would be directory called "common/keycloak" and that this directory should contain a lib directory containing the styles css documents from the "styles" configuration. 3. Reading the codebase, it seems that the semantics of the "import" property is something completetly different. From the ExtendingThemeManager::loadTheme, I can see that the '/' is instead used as a list separator implying that we should attempt loading resources from several sources. (Snippet pasted below). if (theme.getImportName() != null ) { String[] s = theme.getImportName().split( "/" ); themes.add(findTheme(s[ 1 ], Theme.Type. valueOf (s[ 0 ].toUpperCase()))); } So ... I would believe that the configuration in this case would be clearer on a Java Object, JSON or XML form, where one can provide somewhat better semantics than what is possible in a properties file (one could use a List of theme names instead of a single string value to be parsed and interpreted, for example). Mind if I take a stab at implementing a suggestion here? 2015-08-09 17:25 GMT+02:00 Bill Burke < bburke(a)redhat.com > : Only plans right now are to separate our public SPIs and APIs from our private ones. This is a requirement by Red hat before we go into product. Also, a massive backlog of requirements and feature requests has made us rush documentation. The screencast videos haven't been updated since January. It is what it is. Over the next 3-6 months we will catch up on this stuff becuase we are required to before we go into Product. FYI, we already autogenerate REST docs. On 8/9/2015 7:38 AM, Lennart Jörelid wrote: > Hello all, > > A month or so ago, I got curious about Keycloak. Downloaded, set up in a > dev environment, created some custom themes and took a look at the > codebase. I have a few questions, likely because I have missed some > developer documentation: > > * *Codebase concepts*: I frequently try to structure codebases to > highlight its big concepts. For example, if we consider 'themes' to > be such a concept in KeyCloak we might create a folder called > 'themes", with some project wihtin it: (themes-model, themes-spi, > themes-impl-jpa, themes-impl-freemarker, ....). Is there a > description of the codebase structure or concepts currently? > ("mini-SAD") > * *Codebase javadoc:* Do we have a policy for JavaDoc'ing the > Model/API/SPI but perhaps not the implementation classes, other than > with implementation details? > * *Configuration:* Some of the descriptions in the docbook are really > good, and some are more shallow. If we create a standard way of > configuring the parts of keycloak, we could likely generate standard > setup/configuration documentation (somewhat similar to maven plugins > where certain parts of a site documentation is generated from > annotations or JavaDocs). Are there such plans? > > > -- > > -- > +==============================+ > | Bästa hälsningar, > | [sw. "Best regards"] > | > | Lennart Jörelid > | EAI Architect & Integrator > | > | jGuru Europe AB > | Mölnlycke - Kista > | > | Email:lj@jguru.se <mailto: lj(a)jguru.se > > | URL: www.jguru.se < http://www.jguru.se > > | Phone > | (skype): jgurueurope > | (intl): +46 708 507 603 > | (domestic): 0708 - 507 603 > +==============================+ > > > > _______________________________________________ > keycloak-dev mailing list > keycloak-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/keycloak-dev > -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com _______________________________________________ keycloak-dev mailing list keycloak-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/keycloak-dev -- -- +==============================+ | Bästa hälsningar, | [sw. "Best regards"] | | Lennart Jörelid | EAI Architect & Integrator | | jGuru Europe AB | Mölnlycke - Kista | | Email: lj(a)jguru.se | URL: www.jguru.se | Phone | (skype): jgurueurope | (intl): +46 708 507 603 | (domestic): 0708 - 507 603 +==============================+ _______________________________________________ keycloak-dev mailing list keycloak-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/keycloak-dev