Outdated documentation on openstack.org and readthedocs.io

28 views
Skip to first unread message

Adam Romanek

unread,
Feb 18, 2022, 2:58:12 AM2/18/22
to jenkins-job-builder
Hi,

When searching for JJB in Google the very first two hits point at:

  1. https://docs.openstack.org/infra/jenkins-job-builder/
  2. https://jenkins-job-builder.readthedocs.io/en/latest/
The documentation on openstack.org is in version 3.2.1.dev2 (there's no such release, anyway it's probably about 2 years old), while the documentation on readthedocs.io only shows "latest" as its version, so it's really hard to tell if it's up to date.

Could you please help me sort it out?

Best regards,
Adam Romanek

Thanh Ha

unread,
Feb 22, 2022, 8:41:23 AM2/22/22
to jenkins-job-builder
Hi Adam,

I can't remember where the discussion happened (Maybe IRC?) but I recall at one point we decided to move to ReadTheDocs as JJB is no longer an OpenStack project. If I recall correctly this change (https://review.opendev.org/c/jjb/jenkins-job-builder/+/700355) removed the jobs that updated the docs on the OpenStack domain. If you look at the footer on the docs page it references the exact commit that generated the docs. I can confirm  that the RTD version is up to date with the master branch.

There were also discussions about moving JJB to GitHub too on this mailing list but without anyone willing to do the work to get it moved and ensure that all the jobs and automation is transitioned over it's unlikely that will happen anytime soon.

Regards,
Thanh

--
You received this message because you are subscribed to the Google Groups "jenkins-job-builder" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkins-job-bui...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkins-job-builder/081db90f-6087-4a6d-9ffc-fe9099198154n%40googlegroups.com.

Eric Ball

unread,
Feb 22, 2022, 2:08:12 PM2/22/22
to Thanh Ha, jenkins-job-builder
Hi Thanh. What needs to be done to move JJB to Github? I'm willing to put in some time with that and other maintenance tasks, since the LF still heavily utilizes JJB. And I've contributed a feature fairly recently, so I've got a reasonable familiarity with the internals.

Cheers,
Eric Ball
Release Engineer
The Linux Foundation

Thanh Ha

unread,
Feb 22, 2022, 7:01:19 PM2/22/22
to jenkins-job-builder
Hi Eric,

There's the administrative part which we'd need to create a new JJB Org on GitHub then invite all the core reviewers to be owners of the new org and move the 2 repos jjb/python-jenkins and jjb/jenkins-job-builder to GitHub.

The hardest part would be to port all of the existing Zuul jobs over to GitHub Actions (https://opendev.org/jjb/jenkins-job-builder/src/branch/master/.zuul.yaml). There are various jobs that call Tox, deploy to ReadTheDocs, and also the Release to PyPi job that triggers when a Git tag is pushed. If we can replace these jobs over at GitHub then we would be able to move. I have admin permissions for ReadTheDocs and PyPi so can help grant permissions to a bot account. I suspect the best way to go about it is to create the GitHub Actions in a test GitHub repo then propose the changes to Gerrit for the .github/workflows files. Once all the CI bits are proven to work and are checked into the repo we can switch over to the GitHub side and stop using Gerrit.

The thing I'm most worried about in a move of infrastructure though is the continued maintenance of JJB. Currently the Zuul+Gerrit setup at OpenStack is very low maintenance for me so I'm happy to continue supporting the project as long as it takes very little of my time since I no longer use JJB in any of the projects I'm supporting.

I'm happy to pass on maintainership to others if there's real initiative from folks stepping up to maintain the project as I believe JJB should be maintained by people who actually use it day to day. So far I haven't seen much commitment from the community to do so (lack of regular reviews and such) and what I'm concerned about with a move of infrastructure is that JJB will become unmaintained after the project moves. If we do move to GitHub though I think it would make sense for me to take more of a backseat role in the new org after it gets setup.

Hope this helps,
Thanh

Serge S

unread,
Feb 23, 2022, 2:06:04 AM2/23/22
to Thanh Ha, eb...@linuxfoundation.org, jenkins-job-builder
Hello,

The thing I'm most worried about in a move of infrastructure though is the continued maintenance of JJB. Currently the Zuul+Gerrit setup at OpenStack ...

I agree to Than concerns.

Eric, could you clarify what exactly is supposed to be achieved by GitHub move ?
What’s the issue with the current hosting/workflow implementation ?
Do you propose to move git repository hosting only or the CI infrastructure as well ? 

Regards,
Serge.

Andrew Grimberg

unread,
Feb 23, 2022, 12:10:22 PM2/23/22
to Serge S, Thanh Ha, eb...@linuxfoundation.org, jenkins-job-builder
I think Eric was just speaking up about GH because Thanh mentioned it as
something that had been considered in the past.

IMO if JJB moved to GH then, yes, all of the CI would migrate to GHA as
well. No sense trying to keep everything operating on the OpenDev Zuul
environment if everything is in a SCM platform that has a native CI.

Towards the point of continued maintenance. I personally love Gerrit
over GitHub just because the workflow of Gerrit suites me better. The
biggest issue, and we see this with OSS projects we support at the Linux
Foundation (LF), the mind share of devs is on GH and many have a hard
time getting over the hurdle of how Gerrit works so it's harder to get
new talent into a project that is on Gerrit.

In truth, while LF uses JJB a lot, we've been making strides to
transition to Jenkins Pipelines and JJB becomes, less and less needed as
we do that outside of linking Jenkins into the initial repository setup
to pickup the pipeline definitions. JJB is powerful, but in the world of
pipelines it's becoming less needed, especially as more and more plugins
are dying because you don't need them when things are done in Pipelines.

So, while I hate to be a doomsayer, I think that we're going to see a
continued decline in contributions and people willing to step up to help
maintain. Either we can get more people in by switching to GH and things
become easier for new people to contribute, or at some point in the next
year or two we have to concede that the project may go dormant as more
of the industry moves to Pipelines or even other CI platforms.

-Andy-

On 2/22/22 23:06, Serge S wrote:
> Hello,
>
>> The thing I'm most worried about in a move of infrastructure though is
>> the continued maintenance of JJB. Currently the Zuul+Gerrit setup at
>> OpenStack ...
>
> I agree to Than concerns.
>
> Eric, could you clarify what exactly is supposed to be achieved by
> GitHub move ?
> What’s the issue with the current hosting/workflow implementation ?
> Do you propose to move git repository hosting only or the CI
> infrastructure as well ?
>
> Regards,
> Serge.
>
>> On 23 Feb 2022, at 03:00, Thanh Ha <zxi...@gmail.com
>> <mailto:zxi...@gmail.com>> wrote:
>>
>> Hi Eric,
>>
>> There's the administrative part which we'd need to create a new JJB
>> Org on GitHub then invite all the core reviewers to be owners of the
>> new org and move the 2 repos jjb/python-jenkins and
>> jjb/jenkins-job-builder to GitHub.
>>
>> The hardest part would be to port all of the existing Zuul jobs over
>> to GitHub Actions
>> (https://opendev.org/jjb/jenkins-job-builder/src/branch/master/.zuul.yaml
>> <https://opendev.org/jjb/jenkins-job-builder/src/branch/master/.zuul.yaml>).
>> <https://review.opendev.org/c/jjb/jenkins-job-builder/+/700355>)
>> removed the jobs that updated the docs on the OpenStack
>> domain. If you look at the footer on the docs page it
>> references the exact commit that generated the docs. I can
>> confirm  that the RTD version is up to date with the master
>> branch.
>>
>> There were also discussions about moving JJB to GitHub too on
>> this mailing list but without anyone willing to do the work to
>> get it moved and ensure that all the jobs and automation is
>> transitioned over it's unlikely that will happen anytime soon.
>>
>> Regards,
>> Thanh
>>
>> On Fri, Feb 18, 2022 at 2:58 AM Adam Romanek
>> <romane...@gmail.com <mailto:romane...@gmail.com>> wrote:
>>
>> Hi,
>>
>> When searching for JJB in Google the very first two hits
>> point at:
>>
>> 1. https://docs.openstack.org/infra/jenkins-job-builder/
>> <https://docs.openstack.org/infra/jenkins-job-builder/>
>> 2. https://jenkins-job-builder.readthedocs.io/en/latest/
>> <https://jenkins-job-builder.readthedocs.io/en/latest/>
>>
>> The documentation onopenstack.org
>> <http://openstack.org/>is in version 3.2.1.dev2 (there's
>> no such release, anyway it's probably about 2 years old),
>> while the documentation onreadthedocs.io
>> <http://readthedocs.io/>only shows "latest" as its
>> version, so it's really hard to tell if it's up to date.
>>
>> Could you please help me sort it out?
>>
>> Best regards,
>> Adam Romanek
>>
>> --
>> You received this message because you are subscribed to
>> the Google Groups "jenkins-job-builder" group.
>> To unsubscribe from this group and stop receiving emails
>> from it, send an email
>> tojenkins-job-bu...@googlegroups.com
>> <mailto:jenkins-job-bui...@googlegroups.com>.
>> <https://groups.google.com/d/msgid/jenkins-job-builder/081db90f-6087-4a6d-9ffc-fe9099198154n%40googlegroups.com?utm_medium=email&utm_source=footer>.
>>
>>
>> --
>> You received this message because you are subscribed to the
>> Google Groups "jenkins-job-builder" group.
>> To unsubscribe from this group and stop receiving emails from
>> it, send an email
>> tojenkins-job-bu...@googlegroups.com
>> <mailto:jenkins-job-bui...@googlegroups.com>.
>> To view this discussion on the web
>> visithttps://groups.google.com/d/msgid/jenkins-job-builder/CAHrkGO_WzuV%2BZy7Y-134k2wg%3DGdo%3DMFMvhPMOic9ywPJJYPQ%2BA%40mail.gmail.com
>> <https://groups.google.com/d/msgid/jenkins-job-builder/CAHrkGO_WzuV%2BZy7Y-134k2wg%3DGdo%3DMFMvhPMOic9ywPJJYPQ%2BA%40mail.gmail.com?utm_medium=email&utm_source=footer>.
>>
>>
>> --
>> You received this message because you are subscribed to the Google
>> Groups "jenkins-job-builder" group.
>> To unsubscribe from this group and stop receiving emails from it, send
>> an email tojenkins-job-bu...@googlegroups.com
>> <mailto:jenkins-job-bui...@googlegroups.com>.
>> To view this discussion on the web
>> visithttps://groups.google.com/d/msgid/jenkins-job-builder/CAHrkGO_E6yif3W7nJ9-DO1RYc9bTJzOGAXhTsx-TEBX11pMvcA%40mail.gmail.com
>> <https://groups.google.com/d/msgid/jenkins-job-builder/CAHrkGO_E6yif3W7nJ9-DO1RYc9bTJzOGAXhTsx-TEBX11pMvcA%40mail.gmail.com?utm_medium=email&utm_source=footer>.
>
> --
> You received this message because you are subscribed to the Google
> Groups "jenkins-job-builder" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to jenkins-job-bui...@googlegroups.com
> <mailto:jenkins-job-bui...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/jenkins-job-builder/AE84BA24-1530-4561-B474-67CC4DBE253D%40gmail.com
> <https://groups.google.com/d/msgid/jenkins-job-builder/AE84BA24-1530-4561-B474-67CC4DBE253D%40gmail.com?utm_medium=email&utm_source=footer>.

--
Andrew J Grimberg
Manager Release Engineering
The Linux Foundation

NOTICE: The Linux Foundation supports their employees with flexible work
hours. If you recieve mail from me outside of standard business hours
please be aware that I do not expect a response until the next standard
business day.
OpenPGP_signature

Adam Romanek

unread,
Feb 24, 2022, 4:41:23 PM2/24/22
to jenkins-job-builder
On Tuesday, February 22, 2022 at 2:41:23 PM UTC+1 zxi...@gmail.com wrote:
I can't remember where the discussion happened (Maybe IRC?) but I recall at one point we decided to move to ReadTheDocs as JJB is no longer an OpenStack project. If I recall correctly this change (https://review.opendev.org/c/jjb/jenkins-job-builder/+/700355) removed the jobs that updated the docs on the OpenStack domain. If you look at the footer on the docs page it references the exact commit that generated the docs. I can confirm  that the RTD version is up to date with the master branch.

Hi,

Can we then remove the old / outdated documentation from OpenStack. This way we would only have the up-to-date documentation on ReadTheDocs which would become the only source of documentation for JJB and would probably appear on top in search results? Do you know who we should bring into this discussion to remove the old documentation from OpenStack web server(s)?


There were also discussions about moving JJB to GitHub too on this mailing list but without anyone willing to do the work to get it moved and ensure that all the jobs and automation is transitioned over it's unlikely that will happen anytime soon.

The follow-up discussion about the move to GitHub is interesting. IMO GitHub would probably bring more attention to the project from Jenkins community. But the effort is quite big and I'm not sure we have enough motivation to finalize it.

I was thinking about it some time ago and we should probably consider one more option - we could try discussing with Jenkins core maintainers (those behind https://github.com/jenkinsci) about donating the project to Jenkins "core" team (just like they take leadership/ownership of many plugins originally developed by the community). This way JJB could become part of Jenkins "mainstream" (meaning Jenkins core developers would at least consider JJB when introducing potential breaking changes in Jenkins core). I'm not sure if this is even possible, it's just an idea. The are pros and cons of course, but to me the advantage is that JJB would become part of Jenkins core and could potentially even be advertised in Jenkins documentation as a way to implement jobs-as-code / git-ops model and/or some more complex job setups without code duplication. Of course this could be done without donating the project, but it would probably be easier this way, when JJB would officially be part of Jenkins ecosystem.

Anyway, for now let's simply focus on the documentation :)

Regards,
Adam

Thanh Ha

unread,
Feb 25, 2022, 3:38:32 PM2/25/22
to jenkins-job-builder
Hi Adam,

On Thu, Feb 24, 2022 at 4:41 PM Adam Romanek <romane...@gmail.com> wrote:
On Tuesday, February 22, 2022 at 2:41:23 PM UTC+1 zxi...@gmail.com wrote:
I can't remember where the discussion happened (Maybe IRC?) but I recall at one point we decided to move to ReadTheDocs as JJB is no longer an OpenStack project. If I recall correctly this change (https://review.opendev.org/c/jjb/jenkins-job-builder/+/700355) removed the jobs that updated the docs on the OpenStack domain. If you look at the footer on the docs page it references the exact commit that generated the docs. I can confirm  that the RTD version is up to date with the master branch.

Hi,

Can we then remove the old / outdated documentation from OpenStack. This way we would only have the up-to-date documentation on ReadTheDocs which would become the only source of documentation for JJB and would probably appear on top in search results? Do you know who we should bring into this discussion to remove the old documentation from OpenStack web server(s)?

We'll likely need help from the openstack infrastructure folks. They have a mailinglist and IRC channel as documented here https://docs.opendev.org/opendev/system-config/latest/project.html#contributing 

Do you want to try reaching out to them?

 
There were also discussions about moving JJB to GitHub too on this mailing list but without anyone willing to do the work to get it moved and ensure that all the jobs and automation is transitioned over it's unlikely that will happen anytime soon.

The follow-up discussion about the move to GitHub is interesting. IMO GitHub would probably bring more attention to the project from Jenkins community. But the effort is quite big and I'm not sure we have enough motivation to finalize it.

I was thinking about it some time ago and we should probably consider one more option - we could try discussing with Jenkins core maintainers (those behind https://github.com/jenkinsci) about donating the project to Jenkins "core" team (just like they take leadership/ownership of many plugins originally developed by the community). This way JJB could become part of Jenkins "mainstream" (meaning Jenkins core developers would at least consider JJB when introducing potential breaking changes in Jenkins core). I'm not sure if this is even possible, it's just an idea. The are pros and cons of course, but to me the advantage is that JJB would become part of Jenkins core and could potentially even be advertised in Jenkins documentation as a way to implement jobs-as-code / git-ops model and/or some more complex job setups without code duplication. Of course this could be done without donating the project, but it would probably be easier this way, when JJB would officially be part of Jenkins ecosystem.

I suspect Jenkins Core team wouldn't be interested considering JJB is a competitor to their Job DSL / Pipeline feature.
 
Anyway, for now let's simply focus on the documentation :)

Cheers,
Thanh 

Serge S

unread,
Feb 26, 2022, 4:13:54 AM2/26/22
to Thanh Ha, jenkins-job-builder
Hi Thanh,


On 25 Feb 2022, at 23:37, Thanh Ha <zxi...@gmail.com> wrote:

I suspect Jenkins Core team wouldn't be interested considering JJB is a competitor to their Job DSL / Pipeline feature.

I would not consider JJB as a competitor for Jenkins DSL / Pipeline features.

It’s a tool to define and deploy jobs using IaC approach.

Also it has convenient job template / Jinja features to reuse a code and simplify jobs definitions
which may be useful even for Groovy and DSL jobs.

Serge.

Thanh Ha

unread,
Feb 26, 2022, 10:00:25 AM2/26/22
to jenkins-job-builder
On Sat, Feb 26, 2022 at 4:13 AM Serge S <abr...@gmail.com> wrote:
Hi Thanh,

On 25 Feb 2022, at 23:37, Thanh Ha <zxi...@gmail.com> wrote:

I suspect Jenkins Core team wouldn't be interested considering JJB is a competitor to their Job DSL / Pipeline feature.

I would not consider JJB as a competitor for Jenkins DSL / Pipeline features.

It’s a tool to define and deploy jobs using IaC approach.

Job seeding in the DSL / Pipeline world can be achieved with JCasC plugin (https://www.jenkins.io/projects/jcasc/) and the configuration would be very minimal as we'd just need enough configuration to create a Pipeline job. The rest of the config would come from Jenkinsfiles that live in the project repo.
 
Also it has convenient job template / Jinja features to reuse a code and simplify jobs definitions
which may be useful even for Groovy and DSL jobs.

While I agree that full job-templates provided by JJB are pretty nice and the ability to define the jobs as YAML rather than groovy. In Pipeline land it's possible to create a shared library for parts of a job, I guess kinda like macros in JJB so it's not like pipeline jobs cannot template at least parts of their config. Personally I like JJB's approach of having all of the jobs centrally managed in a JJB repo rather than deferring job config to each individual project repo as it's easier for CI teams to adjust job templates.

I wouldn't be against moving JJB to the Jenkins Core project if they are interested in taking ownership of it. The main thing JJB desperately needs right now is active maintainers willing to work on keeping the project alive and developing new features as your subject states. At the current point in time JJB is essentially a project in maintenance mode as the main changes that happen to JJB these days are just adding / updating plugin support. There's currently no work being done in the core JJB codebase.

Regards,
Thanh

Serge S

unread,
Feb 26, 2022, 10:40:53 AM2/26/22
to Thanh Ha, jenkins-job-builder
Job seeding in the DSL / Pipeline world can be achieved with JCasC plugin

Well, I know about the options. 
But they are much less convenient and manageable if we consider hundreds of complex frequently changing jobs.
And there is the issue with DSL parametrized jobs:
If parameters defined at DSL, it's became available/updated only after the job run.
There is no such problem if parameters defined in ’normal’ JJB yaml style and that works perfectly for pipeline projects.

Personally I like JJB's approach of having all of the jobs centrally managed in a JJB repo rather than deferring job config to each individual project repo as it's easier for CI teams to adjust job templates.

I totally agree with you - that’s the way our CI team works.

Best regards,
Serge.

P/S
Hope our discussion will help to find project maintainers;)

--
You received this message because you are subscribed to the Google Groups "jenkins-job-builder" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkins-job-bui...@googlegroups.com.

Adam Romanek

unread,
Feb 27, 2022, 5:11:13 PM2/27/22
to jenkins-job-builder
Hi Thanh,

On Saturday, February 26, 2022 at 4:00:25 PM UTC+1 zxi...@gmail.com wrote:
I wouldn't be against moving JJB to the Jenkins Core project if they are interested in taking ownership of it. The main thing JJB desperately needs right now is active maintainers willing to work on keeping the project alive and developing new features as your subject states. At the current point in time JJB is essentially a project in maintenance mode as the main changes that happen to JJB these days are just adding / updating plugin support. There's currently no work being done in the core JJB codebase.

Out of curiosity, do you have any specific new features in mind? I can imagine a couple but for us, when moving to JJB, the most blocking part was lack of support for some plugins, rather than lack of functionality, which was nearly 100% satisfying (and we contributed the new !j2-yaml tag to cover the missing part, but we could have lived without it). So I'm thinking what new features could actually make the future of this project in bright colors?

Best,
Adam 

Ian Wienand

unread,
Feb 27, 2022, 7:09:06 PM2/27/22
to jenkins-job-builder
Thanks for bringing this up.

We stopped publishing docs there with change [1] some time ago.  Although technically this project could still push an update there creating redirects, it is a lot of fiddling about for no benefit. 

This lives on AFS, so I just dropped a .htaccess file to do a 301 redirect, which should get search indexes updated soon.  Any problems, let me know, or #opendev OFTC will have others who can help too.

Thanks,

-i

Adam Romanek

unread,
Feb 28, 2022, 2:34:52 AM2/28/22
to jenkins-job-builder
I can see the Openstack link in search results redirects to RTD, perfect. Thank you Ian! 

Best,
Adam

Thanh Ha

unread,
Mar 1, 2022, 8:05:14 AM3/1/22
to jenkins-job-builder
I don't have any specific features in mind but if there's no one who works in the core codebase (and also our library project python-jenkins) then there is no expertise to maintain and fix things in these areas when something does come up.

Regards,
Thanh

Reply all
Reply to author
Forward
0 new messages