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

Mon Aug 10 03:43:55 EDT 2015

Hello Stian,

I believe it is a bit of both; documentation can assist to a certain degree
but the codebase holds the

I find it considerably simpler to make a concept (read "themes", "roles",
"workflow") usable if its implementation is somewhat centered in a module,
potentially with several subprojects. I was planning to use KeyCloak as an
OOTB solution, but found it simpler to dig into the codebase to see how
things are implemented to get it going. I can elaborate - if you wish - in
another email (private or to the list).

... and while digging into the codebase, I found some things that I wanted
to share and possibly contribute, partly because I found it somewhat
difficult to understand how the configuration related to the file system.
Also, some best practises were not touched upon in documentation or
examples - and while that is understandable considering that KeyCloak is a
project, I figured I could perhaps submit a suggestion [in the form of a
GitHub pull request] for simplifying somewhat.

2015-08-10 8:56 GMT+02:00 Stian Thorgersen <stian at redhat.com>:

> 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
>

-- 

--
+==============================+
| 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/20150810/10222aed/attachment.html 