Goal of the contribution

The tutorial "Build a Java app with Maven" (https://jenkins.io/doc/tutorials/build-a-java-app-with-maven/ ) is a great one for starters.
However, the time (20 - 40 min) and requirements needed to complete it are cumbersome.
Also, there is a lot of moving parts here (Docker, GitHub, Copy & Paste from the web browser) that can make the tutorial not working or difficult to maintain.

We want to propose to update this tutorial content using a KataCoda (https://www.katacoda.com/) course, that will provide step by step instructions along with an online sandbox environment (no need to run jenkins locally).

We want to provide a PR with a working Proof Of Concept that can be discussed ("What it looks like?", "What are the corner cases/risks using KataCoda?", "Is this tutorial the right one to feature this kind of integration?", etc.).

Last goal is to provide an example of contribution to newcomers to the project.

Contributors

Tutorial Audit

Current flow

The current tutorial follows the main steps:

1. Requirements
2. Starting Jenkins using Docker
3. Forking the repository on GitHub and cloning it locally
4. Access and Configure Jenkins using the "First Time" Wizard
5. Create a Pipeline Job in the Classic UI
6. Add a Jenkinsfile in the git repository, and commit
7. Run the pipeline and see it running in Blue Ocean
8. Iterate 3 times until you have a 3 steps "Build -> Test -> Deploy" Pipeline

What to keep or throw away

We wanted to put boundaries on our work, based on paint points and gain from
KataCoda, compared to the current tutorial:

1. Should be kept outside KataCoda, and simplified (HTML5 webbrowser and WebSockets support)
2. This section can be deleted: KataCoda will take care of this
3. Discussion about the constraints of using GitHub (account to create, not able to reach in China or some companies, adding addition complexity to the tutorial), versus the advantages (tracking of forks, it provides a platform we don't have to maintain, having an upstream project allow fixed behaviours)

Consensus to not bother the end user with GitHub

4. Discussion about pros and cons of having the Wizard versus a pre-configured Jenkins instance.

5. We keep it as it is today: we don't want to cover the topic "Use the Blue Ocean experience for creating a Pipeline"
6. We would want to validate if we can use the KataCoda's integrated IDE to provide a fixed environment.
7. Keep it as it is today.
8. Keep it as it is today.

If you're planning to run through multiple tutorials from this page, the Run Jenkins in Docker section on any given tutorial only needs to be performed once. Hence, if you're running through one of these tutorials for the first time, you can skip the Run Jenkins in Docker section in other tutorials. This is mentioned at the end of each tutorial's introductory section (in the paragraph just before Prerequisites), although I guess it might be easy to miss. FYI, the Asciidoc source for each tutorial page (so far) re-uses the same Run Jenkins in Docker content (as an Asciidoc inclusion).

The reason I designed these tutorials this way is that I wanted them to target users (especially those of the OSS community) who are new to Jenkins and want to quickly get an instance up and running on their own computer so they can see how Jenkins is meant to work. Having said that, if there were an option of an already-running (perhaps cloud-based) Jenkins instance that the OSS community could access relatively easily, then I probably would have written these tutorials differently. By no means is the current wording of these tutorials set in stone (they've evolved significantly over the last 6 months).

Giles Gaskell
added a comment - 2018-02-07 10:45 - edited This looks good Damien Duportal
Just a couple of points to add about these tutorials :
If you're planning to run through multiple tutorials from this page, the Run Jenkins in Docker section on any given tutorial only needs to be performed once. Hence, if you're running through one of these tutorials for the first time, you can skip the Run Jenkins in Docker section in other tutorials. This is mentioned at the end of each tutorial's introductory section (in the paragraph just before Prerequisites ), although I guess it might be easy to miss. FYI, the Asciidoc source for each tutorial page (so far) re-uses the same Run Jenkins in Docker content (as an Asciidoc inclusion).
The reason I designed these tutorials this way is that I wanted them to target users (especially those of the OSS community) who are new to Jenkins and want to quickly get an instance up and running on their own computer so they can see how Jenkins is meant to work. Having said that, if there were an option of an already-running (perhaps cloud-based) Jenkins instance that the OSS community could access relatively easily, then I probably would have written these tutorials differently. By no means is the current wording of these tutorials set in stone (they've evolved significantly over the last 6 months).
I've deliberately kept the Run Jenkins in Docker content deliberately separate from the content in the Docker section of the Installing Jenkins page . This is because the Installing Jenkins content contains a lot more information and my intent was to minimize overloading readers of the tutorial with too much information.
Anyway, I'm keen to see how the proposals above transpire!

Giles Gaskell
added a comment - 2018-02-07 10:57 Btw ... very minor point, in the Tutorial Audit > Content Flow (above), I believe 3 and 4 should be switched around (as 4 is meant to follow directly on from 2).

Just to clarify (as you've already indicated) that this is creating the Pipeline job or project itself through the classic UI, since creating the Pipeline through the classic UI implies this, which means the Jenkinsfile itself is not stored in source control.

Giles Gaskell
added a comment - 2018-02-08 03:39 - edited Create a Pipeline Job in the Classic UI
Just to clarify (as you've already indicated) that this is creating the Pipeline job or project itself through the classic UI, since creating the Pipeline through the classic UI implies this , which means the Jenkinsfile itself is not stored in source control.