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

Mon Aug 10 02:56:54 EDT 2015

Is the main issue here that "import" can be a list in theme.properties? If so that's really a documentation issue, not organization of code-base.

BTW Keycloak is an OOTB solution so you should refer to documentation and examples (I know it's lacking in some places) not the code base. We are targeting non-Java developers and others that just wants something that works without coding. For extending/customization of Keycloak we plan to improve on documentation and clean-up Java APIs that are public.

----- Original Message -----
> From: "Lennart Jörelid" <lennart.jorelid at gmail.com>
> To: keycloak-dev at 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 at 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 at jguru.se <mailto: lj at 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 at 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 at 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 at jguru.se | URL: www.jguru.se | Phone
> | (skype):    jgurueurope
> | (intl):     +46 708 507 603
> | (domestic): 0708 - 507 603
> +==============================+
> 
> _______________________________________________
> keycloak-dev mailing list
> keycloak-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/keycloak-dev