Uploaded image for project: 'Jenkins Website'
  1. Jenkins Website
  2. WEBSITE-343

Add Pipeline Best Practice Documentation for Jenkins.io

    Details

    • Similar Issues:

      Description

      Based on the blog by Sam Van Oort we need to add a Pipeline handbook section for Best Practices. 

      We should start by recommending Declarative Pipeline for all Jenkinsfiles and Scripted Pipeline for Shared Libraries. Declarative wasn't part of Sam's blog but needs to be there.

      Other sections we should cover:

      • Using the 'replay' function for testing both in the UI and the CLI
      • Using the CLI Linter for Jenkinsfiles (could have a shell script that Lints the Jenkinsfile and then runs replay with Jenkinsfile for more rapid iteration)
      • Using Docker Pipeline correctly
      • Appendix list Groovy idioms that do not work and links to the JIRA for this.

        Attachments

          Issue Links

            Activity

            Hide
            recampbell Ryan Campbell added a comment - - edited

            We don't have a listing of the groovy language features that are supported in pipeline (or workarounds for the lack thereof). This is often asked about. There are tests in Groovy CPS which should provide some guidance.

            Show
            recampbell Ryan Campbell added a comment - - edited We don't have a listing of the groovy language features that are supported in pipeline (or workarounds for the lack thereof). This is often asked about. There are tests in Groovy CPS which should provide some guidance.
            Hide
            rtyler R. Tyler Croy added a comment -

            Sam's blog post contains very very advanced Scripted Pipeline scaling tips which I don't think fit in any current part of the user handbook.

             

            I'm not saying there is no place for these tips, but rather if we were to cram them into the current structure, we would be confusing lots of users who are referring to the handbook for less advanced topics.

             

             

            The replay/linting stuff is already going to be covered in WEBSITE-296.

             

             

            As far as "groovy idioms", I would rather the Pipeline development team fix the issues making Pipeline-necessary-idiom documentation necessary (give me .each!)

            Show
            rtyler R. Tyler Croy added a comment - Sam's blog post contains very very advanced Scripted Pipeline scaling tips which I don't think fit in any current part of the user handbook.   I'm not saying there is no place for these tips, but rather if we were to cram them into the current structure, we would be confusing lots of users who are referring to the handbook for less advanced topics.     The replay/linting stuff is already going to be covered in WEBSITE-296 .     As far as "groovy idioms", I would rather the Pipeline development team fix the issues making Pipeline-necessary-idiom documentation necessary (give me .each!)
            Hide
            hrmpw Patrick Wolf added a comment -

            R. Tyler Croy Liam Newman  There is a "Best Practices" section of the handbook.  We wouldn't need to move in the entirety of Sam's blog but some of the topics are probably worth including. In addition we are looking at how we can bring in Docs for Docker Pipeline and Checkpoints.  

            What is the best way to proceed here?

            Show
            hrmpw Patrick Wolf added a comment - R. Tyler Croy Liam Newman  There is a " Best Practices " section of the handbook.  We wouldn't need to move in the entirety of Sam's blog but some of the topics are probably worth including. In addition we are looking at how we can bring in Docs for Docker Pipeline and Checkpoints.   What is the best way to proceed here?
            Hide
            rtyler R. Tyler Croy added a comment -

            The best way to proceed is to think of/clarify who the audience for this kind of content is, that helps make it clearer where in the handbook such content should go. That "Best Practices" placeholder chapter I actually think we should remove, it doesn't seem to belong any longer (I probably suggested it in the first place). Introducing content like advanced scalable Pipeline pro-tips before Pipeline itself doesn't make sense either.

            Perhaps a section in the Pipeline chapter titled "Advanced Scripted Pipeline?" I think wherever it goes must be very very blatantly titled "SCRIPTED" pipeline since that content is severely Scripted-oriented rather than Declarative which is the default for that whole Pipeline chapter.

            All that said, for this content to be incorporated, it needs to be converted from lists of lists to readable prose. I don't expect Liam Newman or myself to have time anytime soon for this kind of niche content unfortunately.

            The Docker Pipeline stuff is already planned to come in, Checkpoints is not something that's open source as far as I have seen.

            Show
            rtyler R. Tyler Croy added a comment - The best way to proceed is to think of/clarify who the audience for this kind of content is, that helps make it clearer where in the handbook such content should go. That "Best Practices" placeholder chapter I actually think we should remove, it doesn't seem to belong any longer (I probably suggested it in the first place). Introducing content like advanced scalable Pipeline pro-tips before Pipeline itself doesn't make sense either. Perhaps a section in the Pipeline chapter titled "Advanced Scripted Pipeline?" I think wherever it goes must be very very blatantly titled "SCRIPTED" pipeline since that content is severely Scripted-oriented rather than Declarative which is the default for that whole Pipeline chapter. All that said, for this content to be incorporated, it needs to be converted from lists of lists to readable prose. I don't expect Liam Newman or myself to have time anytime soon for this kind of niche content unfortunately. The Docker Pipeline stuff is already planned to come in, Checkpoints is not something that's open source as far as I have seen.
            Hide
            hrmpw Patrick Wolf added a comment -

            Part of documenting the best practices for Pipeline, in my opinion, would be, first and foremost, to recommend Declarative Pipeline upfront. Using that as the foundation we could then give suggestions on how to take advantage of agents and external tools to do the work instead of trying to do things in Groovy on the master JVM.  Some of the blog content would fit there but I didn't mean to imply that would dump the entire blog in.

            Show
            hrmpw Patrick Wolf added a comment - Part of documenting the best practices for Pipeline, in my opinion, would be, first and foremost, to recommend Declarative Pipeline upfront. Using that as the foundation we could then give suggestions on how to take advantage of agents and external tools to do the work instead of trying to do things in Groovy on the master JVM.  Some of the blog content would fit there but I didn't mean to imply that would dump the entire blog in.

              People

              • Assignee:
                Unassigned
                Reporter:
                hrmpw Patrick Wolf
              • Votes:
                1 Vote for this issue
                Watchers:
                4 Start watching this issue

                Dates

                • Created:
                  Updated: