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

From: "Lennart Jörelid" <lennart.jorelid(a)gmail.com&gt; To: "Stian Thorgersen" <stian(a)redhat.com&gt; Cc: keycloak-dev(a)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).

... 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(a)redhat.com&gt;: > 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(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 > -- -- +==============================+ | 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 +==============================+

From: "Lennart Jörelid" <lennart.jorelid(a)gmail.com&gt; To: "Stian Thorgersen" <stian(a)redhat.com&gt; Cc: keycloak-dev(a)lists.jboss.org Sent: Monday, 10 August, 2015 11:57:34 AM Subject: Re: [keycloak-dev] Fwd: Concept structure in the VCS? Hello there, 2015-08-10 10:04 GMT+02:00 Stian Thorgersen <stian(a)redhat.com&gt;: > > 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. > I believe that some implementation details which carry over into the model/configuration domain (i.e. semantics of configuration or implementation details) should likely be documented for clarity - even if they are not part of APIs or SPIs. However, I can appreciate that these types of changes or documentation have less priority than other tasks. We all work in some kind of sprint context where priorities have to be made.

:) > ... 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. > I agree; it is important that changes constitute improvements overall. I'll ponder, create a JIRA issue and do the changes in my private KeyCloak fork - it can be discussed and dissected there rather than in the KeyCloak standard repository.

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