Track documentation updates for Jenkins migration docs from feedback
This is just a todo list for processing feedback coming from customer interviews related to the Jenkins Importer.
Ideas of improvements for Jenkins migration docs
- [-] Mapping of plugins to how to achieve the same thing in GitLab (moved to #208270 (closed))
-
Examples of how to achieve various specific things (manual jobs to deploy to production) - [-] Best practices (moved to #210292)
-
IRC channel, some kind of tip line or knowledge base specifically supporting questions during a migration - [-] Example of converting a typical Jenkins pipeline, end to end (moved to #208273 (closed))
Migration Docs
-
Cron/scheduling and how that works could be explained better for someone coming from Jenkins -
The triggering concept is similar that it is not intuitive for someone coming from Jenkins -
Jobs that are not really associated with anything (little tasks that don’t go with any particular project/repo). Little utility things that people would run. -
How stages work vs. DAG vs. Child/parent pipelines (should link to new pipeline architectures page) - [-] Concept translation guide would be super helpful. A video here might be extra valuable. (moved to #210291 (closed))
- [-] A speed-up/efficiency guide (are we building this thing right?) would be good especially when implementing things for the first time. (moved to #210293)
-
Resistance came more around prioritisation (we should be building features not moving CI around). People didn’t understand the value until it was already delivered, then they did. -
Somehow indicating the importance of vision to support the migration from the leadership team. Having a sponsor here helps
Migrating
-
Biggest piece that drove success was education -
GitLab was simpler, but was new so a case needed to be made for why it was worth it -
Had to look at each job in isolation and there was no real way to convert it because it was all UI-edited and jenkins.yml was cumbersome to use. - [-] It was a lot of work to move the older jobs, and Windows jobs that were lacking docs (#210294)
-
Was worth it to go through the pain, but a huge challenge on the people and technology side. Paid back 10x already -
Have more features now than they ever did in Jenkins
Jenkins docs improvements
-
Add parallel keyword - [-] Add more examples, examples of Maven, running different kinds of tests, other common things (moved to #210295 (closed))
-
Example of creating the container for the build already containing all your tools, then this can actually be shared with Jenkins. And check in the scripts. Take as much configuration out of Jenkins as possible (plugins, config) and put it in scripts, then both sides can use it. Then you can also test from your own machine too. -
Should also describe how to use templates, set up a templates project using include. This can also contain scripts and other things.
General migration challenges
-
The way artefacts work when being passed from job to job in Jenkins is very different and a big source of confusion. Each job does not have the artefacts any more and it’s hard for people to understand. This is a case for #29265 and also we could improve the Jenkins docs around. - [-] Helping to move secrets from Jenkins to GitLab is also confusing, either automated or docs or both. (moved to #210296 (closed))
-
Converting agents to runners was a big headache where people were doing Windows builds and the central team couldn’t’ manage these with containers and so this slowed down adoption. Setting up the Windows runner just the way they need was difficult (or at least they felt it was). -
Labeling runners makes more sense and is better than what Jenkins does. The combination of setting labels in the project and the runner self-selecting projects is powerful and should be documented clearly in the Jenkins migration docs.
Edited by Jason Yavorska