Proposal: Documenting the Jenkins themes support policy
Oleg Nenashev
Dear all,
TL;DR: We suggest to document the theme support policy and to explicitly set low expectation about layout compatibility in the Jenkins core and plugins
Context. There is an ongoing effort focused on improving Jenkins look-and-feel which is currently coordinated by the Jenkins UX SIG. This is an important area, because nowadays Jenkins user interface is widely considered dated. It impacts the project adoption, and causes negative optics which does not help to onboard new contributors. We have a number of related initiatives in our roadmap, and there is a consensus in the community about the UI changes. One of the major concerns on the UI fronts is retaining compatibility with supported platforms and use-cases. We have recently documented the browser support policy, but it is not the only case we need to keep in mind. Theme compatibility is one of the widely raised concerns, and it was brought up again in the context of a Jenkins dark theme project idea for the Jenkins UI/UX Hackfest.
Problem. There are widely used Simple Theme Plugin (25k installations, ~10% of instances) and Login Theme (1.5k installations) which allow setting up custom themes. Login Theme uses a documented specification for the layouts, and we can avoid breaking changes there. On the other hand Simple Theme Plugin basically allows overriding/extending Jenkins CSS and frontend by arbitrary user-supplied CSS and Javascript files. It is a very powerful engine which allows changing almost everything in the UI, but at the same time it makes themes very fragile. There are also other ways to override themes that share the same problem. Any frontend change (layout, CSS, Javascript, resources and images, etc.) in the Jenkins core or a plugin may break custom themes. There is no specification which documents the supported ways to override configs. And we have no real way of testing that. And, still, we believe it is important to proceed with UI changes.
Proposal. We suggest to explicitly document the theme support policy in the Simple Theme Plugin plugin documentation and in Jenkins user documentation. We suggest to explicitly document the current state of affairs even if it may be perceived negatively by potential theme users. In our opinion it is better to set expectations early than to break their layouts with major changes in Jenkins.
Suggested points in the theme support policy:
At the moment Jenkins project does not provide specification for layouts/CSS, and we do not guarantee backward or forward compatibility. We try to reflect major changes in the changelog (e.g. see the ‘developer’ changes in the Jenkins changelog), but minor changes may not be included there.
Themes are provided “as is”, without warranty of any kind, implicit or explicit. Jenkins core and other component updates may break theme compatibility without notice
Users are welcome to report discovered compatibility issues to theme maintainers, to submit fixes or to fork and fix their themes. We will generally reject bug reports to the Jenkins core/plugins involving broken UI when a custom theme, but we will consider pull requests which restore compatibility and do not create obstacles for further Web UI evolvement
Theme maintainers are expected to document compatibility for their themes (examples: Jenkins Atlassian Theme, Neo2). It includes:
required theme plugins and versions,
target Jenkins core version,
plugin versions if plugin (UI/CSS are overridden),
browser compatibility.
Theme maintainers are advised to version themes with tags on Git and to maintain changelogs with explicit references to changes in the supported versions (e.g. see our release drafter documentation as one of the ways to automate changelogs).
For theme listing in the Jenkins project documentation and other resources: Themes listed by the Jenkins project are expected to have an OSI-approved license so that users can freely modify and redistribute them as long as license conditions and attribution requirements are followed
“Other resources” is a groundwork for a theme marketplace or other similar promotion engines
Later, once the Jenkins UI rework reaches its destination and the UI becomes more stable, we could consider creating specifications for theme extensibility so that we could make themes more stable and maintain compatibility. But, in my opinion, we are not there yet.
If everyone (especially Tobias @TobiX Gruetzmacher and UX SIG folks) agree with these guidelines, I will proceed and submit pull requests to https://www.jenkins.io/doc/book/managing/ and to the SimpleTheme Plugin. Any feedback and suggestions will be appreciated!
Best regards,
Oleg Nenashev and Félix Queiruga
Hickel, Kelly
yes
-Kelly
--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to
jenkinsci-de...@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/jenkinsci-dev/CAPfivLDQ9iZcBDTZtxtW42q9OAbKs3HRr76Oqfto0Mp3RccNSA%40mail.gmail.com.
Tim Jacomb
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/f63f4f482b5748e784744739c3dfacb8%40hou-exmbprd-03.adprod.bmc.com.
Jeremy Hartley
You received this message because you are subscribed to the Google Groups "Jenkins User Experience" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-ux...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-ux/CAH-3BidJgjCYEEnZj4s_HcZd66Q1Eo%2BvyOD2VetMpVkE_UZvBA%40mail.gmail.com.
Tobias Gruetzmacher
> Proposal. We suggest to explicitly document the theme support policy
> in the Simple Theme Plugin plugin documentation and in Jenkins user
> documentation. We suggest to explicitly document the current state of
> affairs even if it may be perceived negatively by potential theme
> users. In our opinion it is better to set expectations early than to
> break their layouts with major changes in Jenkins.
that. I only adopted the plugin with the intent to keep it alive and
"modern" ("recent" examples: Adding CasC support)
> Suggested points in the theme support policy:
>
> explicit. Jenkins core and other component updates may break theme
> compatibility without notice
This sounds like a reasonable baseline. My own theme (Neo2, basically
only created because the jenkins-contrib-themes GitHub organisation
"died" and the sole maintainer of neo & material seems to be MIA) is
currently operating in "fix if something breaks, build each commit from
master" mode, but I have started tagging and releasing irregular
versioned snapshots some time ago (yeah, without "real" changelog).
I'm not a HTML/CSS/UX wizard, so most changes are just "fixing if
anything breaks" already.
> If everyone (especially Tobias @TobiX Gruetzmacher and UX SIG folks)
> agree with these guidelines, I will proceed and submit pull requests
> to https://www.jenkins.io/doc/book/managing/ and to the SimpleTheme
> Plugin. Any feedback and suggestions will be appreciated!
core (those already merged and those still in the pipeline) and I don't
think existing themes should hamper progress in this area.
Regards, Tobias