Add best practices page

content/doc/book/using/_chapter.yml

@@ -1,5 +1,6 @@
 ---
 sections:
+  - best-practices
   - working-with-projects
   - using-credentials
   - searchbox

content/doc/book/using/best-practices.adoc

@@ -0,0 +1,192 @@
+---
+layout: section
+title: Best Practices
+---
+ifdef::backend-html5[]
+:description:
+:author:
+:sectanchors:
+:toc:
+:toclevels: 4
+:hide-uri-scheme:
+ifdef::env-github[:imagesdir: ../resources]
+ifndef::env-github[:imagesdir: ../../resources]
+endif::[]
+
+Continuous Integration (CI) with automated test execution and trend analysis has revolutionized the way companies approach build management, release management, deployment automation, and test orchestration.
+In this section, we will explore best practices that aim to enlighten executives, business managers, software developers, and architects about the invaluable contributions Jenkins can make throughout the project lifecycle.
+
+== Automate job definition
+
+Jenkins has the ability to automatically create, update, and delete jobs based on the repositories it identifies in your software configuration management system. 
+Leverage this feature and optimize your job management by structuring your job definitions in a way that maximizes the benefits offered by Jenkins' automatic job management capabilities.
+
+There are multiple alternatives for automatic job management, including:
+
+* <<Use organization folders>> - create, update, and delete multibranch Pipeline folders and Pipeline jobs automatically (preferred)
+* <<Use multibranch Pipelines>> - create, update and deleted Pipeline jobs automatically
+* <<Pipeline>> - Manually defined Pipeline jobs for more control over the job management process.
+
+=== Use organization folders
+
+Organization Folders provide a convenient way to automate the creation and deletion of jobs in Jenkins as repositories and branches are added or removed. 
+If you are using GitHub organizations, Bitbucket teams, GitLab groups, or Gitea organizations, Jenkins can automatically detect the creation of a new repository and generate a Multibranch Pipeline project for it.
+
+Refer to the link:/doc/book/pipeline/pipeline-as-code/#organization-folders[organization folders] documentation for more details.
+
+.GitHub organization folders
+video::LbXKUKQ24T8[youtube,width=800,height=420]
+
+.GitLab group folders
+video::it6TOeQ6EHg[youtube,width=800,height=420]
+
+.Bitbucket project folders
+video::85b6fiVolfk[youtube,width=800,height=420]
+
+.Gitea organization folders
+video::NO3sZWRxgQM[youtube,width=800,height=420]
+
+=== Use multibranch Pipelines
+
+If you are unable to use organization folders, you can opt for multibranch Pipelines as an alternative.
+However, it's important to note that organization folders are preferred over multibranch Pipelines because they provide the automation of creating and deleting multibranch projects when repositories are added or removed.
+
+.GitHub multibranch Pipelines
+video::aDmeeVDrp0o[youtube,width=800,height=420]
+
+.GitLab group folders
+video::y4XGFluzPHY[youtube,width=800,height=420]
+
+.Bitbucket project folders
+video::LNfthmZuRDI[youtube,width=800,height=420]
+
+Refer to the link:/doc/book/pipeline/pipeline-as-code/#multibranch-pipeline-projects[multibranch Pipelines] documentation for more details.
+
+=== Use Pipeline
+
+If organization folders are not an option for you, consider using multibranch Pipelines as an alternative.
+However, it's important to highlight that organization folders are preferred, due to their ability to automatically create and delete multibranch projects when repositories are added or removed.
+
+Refer to the link:/doc/book/pipeline/[Pipeline] documentation for more details.
+
+.Differences between Freestyle and Pipeline in Jenkins
+video::IOUm1lw7F58[youtube,width=800,height=420]
+
+== Manage your jobs
+
+Jenkins job definitions can be managed and optimized to enhance user interactions and productivity.
+
+=== Report build results
+
+Charts and graphs provide valuable insights into project status and progress, showcasing trends and patterns.
+Automated test results including unit tests, integration tests, and end-to-end tests can reveal brittleness or instability. 
+Coverage reports help identify areas where automated tests are not being executed.
+Compiler warning messages often serve as the first indication of a problem.
+Static analysis tools are effective in reporting risky code or code with potential security risks.
+Performance test results help identify delays or areas of concern.
+
+The plugin:warnings-ng[Warnings Next Generation] plugin provides convenient access to many reports including:
+
+* Compiler warnnings and errors (like gcc, clang, javac, or  golang)
+* Static analysis warnings and errors (spotbugs, checkstyle, pmd, lint, cpd, or Simian)
+* Code coverage reports
+
+.How to use the Warnings Next Generation plugin
+video::tj3xYFA6Q2o[youtube,width=800,height=420]
+
+=== Build on agents
+
+Use agents to perform builds instead of running builds on the controller.
+Utilizing agents offers enhanced safety and scalability.
+
+Refer to the link:/doc/book/security/controller-isolation/[controller isolation] documentation for more details.
+
+=== Show failures to the right people
+
+Configure notifications for failing and unstable jobs, to ensure that the right people receive them without causing unnecessary distractions for others.
+Many Jenkins users prefer to be notified only when a failure is likely their responsibility.
+This approach acknowledges that if they are not responsible for the failure, they may not be the most suitable person to investigate it.
+
+Refine your notification system to prioritize notifying the most recent committers when new test failures occur, as they are likely to be the cause of the issue.
+
+.Sending Slack notifications
+video::EDVZli8GdUM[youtube,width=800,height=420]
+
+=== Use simple project names
+
+Jenkins utilizes project names for organizing related folders.
+However, it's important to note that certain tools may encounter issues with spaces, dollar signs, or similar characters in file paths.
+To ensure compatibility, it's recommended to limit project names to alphanumeric characters` [a-zA-Z0-9_-]+`.
+To enhance the appearance of project names, you can utilize the *Display Name* feature.
+This allows you to customize the presentation, while maintaining the restricted characters in the underlying project name.
+To enforce consistent naming conventions across all projects, enable the "Restrict project naming" setting in the system configuration.
+This ensures that naming restrictions are enforced uniformly.
+
+=== Fingerprint your dependencies
+
+When dealing with interdependent projects, it can be challenging to keep track of which version of one project is used by another.
+However, Jenkins offers a solution called "file fingerprinting" to simplify this process.
+
+Refer to the link:/doc/book/using/fingerprints/[fingerprinting page] for more information.
+
+=== Don't use the Maven job type
+
+Jenkins has been providing the plugin:maven-plugin[Maven integration plugin] for many years, allowing users to create Maven projects using the "Maven project" selection from the Jenkins "New item" menu.
+While the Maven job type offers a higher level of integration with Maven builds, it can sometimes introduce unnecessary complexities due to this deep integration.
+
+Consider using organization folders, multibranch Pipelines, or Pipeline jobs instead of the Maven job type.
+These alternatives provide more flexibility and simplicity in managing your Jenkins jobs and workflows.
+
+The Jenkins project uses organization folders to build link:https://ci.jenkins.io/job/Core/[Jenkins core] and link:https://ci.jenkins.io/job/Plugins/[Jenkins plugins] on ci.jenkins.io.
+A Jenkins Pipeline builds Maven projects easily and provides much better control for Maven users.
+
+Refer to the link:https://plugins.jenkins.io/maven-plugin/#plugin-content-risks[Maven plugin documentation] for more details.
+
+== Manage your controller
+
+The Jenkins controller plays a crucial role as a central resource, requiring effective management for optimal performance.
+By following these practices, you can ensure that your controller provides the best possible experience for users.
+
+=== Secure the controller
+
+Jenkins installations come with security enabled by default, which is a crucial aspect of protecting your system.
+While it is technically possible to disable security, it is strongly advised **not** to do so.
+Disabling security can leave your Jenkins instance vulnerable to unauthorized access and potential security breaches.
+It is important to maintain a secure environment by keeping security enabled at all times.
+
+Refer to the link:/doc/book/security/securing-jenkins/[securing Jenkins] chapter of the User Handbook for more details.
+
+=== Back up regularly
+
+Even the most reliable systems can experience failures. 
+That's why it's crucial to be prepared and regularly check the health of your backups.
+Backups are a critical component of ensuring the integrity and availability of your data.
+Regularly testing your backups and verifying their completeness and restorability will help you mitigate the impact of any potential failures and ensure that your data can be recovered effectively when needed.
+Prioritizing backup health and conducting routine checks is essential for maintaining a robust and resilient system.
+
+More details can be found in the link:/doc/book/system-administration/backing-up/[backup documentation].
+
+=== Avoid scheduling overload
+
+Schedule your jobs strategically to balance the number of jobs running concurrently.
+If you're using timer triggers or periodic polling, consider using the `H` syntax in the cron expression to introduce scheduling jitter.
+This helps to distribute the start times of jobs more evenly and prevent them from all starting simultaneously.
+Additionally, take advantage of predefined tokens like `@hourly` to further distribute the starting times of your jobs.
+These tokens can help create a more balanced schedule and reduce the likelihood of resource contention.
+
+By implementing these scheduling techniques, you can optimize the utilization of your resources and ensure a smoother execution of your jobs.
+
+=== Avoid resource collisions
+
+When multiple jobs run simultaneously, there is a possibility of collisions occurring, especially if they require exclusive access to certain resources or set-up services.
+To prevent interference and ensure smooth execution, it is important to manage resource access effectively.
+For builds involving databases or networked services, it is crucial to implement measures that prevent conflicts.
+The plugin:lockable-resources[Lockable Resources plugin] offers fine-grained resource-locking capabilities for Jenkins jobs.
+By using this plugin, you can ensure that only one job has access to a specific resource at a time, avoiding conflicts and ensuring proper synchronization.
+In cases where resource locking with the lockable resources plugin is not sufficient, you can further control concurrent builds using the plugin:throttle-concurrent-builds[Throttle Concurrent Builds plugin].
+This plugin allows you to limit the number of builds that can run simultaneously, providing additional control and preventing overload on shared resources.
+
+By leveraging these plugins, you can manage resource conflicts and concurrency effectively, ensuring smooth and reliable execution of your Jenkins jobs.
+
+.How to use lockable resources
+video::y_z8mqV8G68[youtube,width=800,height=420]