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

[Lennart Jörelid]

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
+==============================+
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/keycloak-dev/attachments/20150809/e6e10652/attachment.html