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

Stian Thorgersen stian at redhat.com
Mon Aug 10 04:04:54 EDT 2015 


----- Original Message -----
> From: "Lennart Jörelid" <lennart.jorelid at gmail.com>
> To: "Stian Thorgersen" <stian at redhat.com>
> Cc: keycloak-dev at lists.jboss.org
> Sent: Monday, 10 August, 2015 9:43:55 AM
> Subject: Re: [keycloak-dev] Fwd: Concept structure in the VCS?
> 
> 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).

The code base is already centered as modules, but we'll probably change things somewhat to make public api/spis stand out more. We won't document or add Javadoc to any parts of the code base that aren't public api/spis.

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

Sure - I'd welcome improvements, but please write an email top keycloak-dev mailing list outlining each improvement before working on a PR. Refactoring of the code should be done with great consideration as it makes life hard for existing developers and contributors when things change.

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

More information about the keycloak-dev mailing list