diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc deleted file mode 100644 index 9b57c62ce..000000000 --- a/CONTRIBUTING.adoc +++ /dev/null @@ -1,186 +0,0 @@ -:toc: - -# Contributors Guide - -## Local Environment - -.Tools -|=== -| Tool | Purpose - -| https://gradle.org[Gradle] -| Used to run unit tests, package the JPI, and publish the plugin - -| https://github.com/casey/just[Just] -| A task runner. Used here to automate common commands used during development. - -| https://www.docker.com/get-started[Docker] -| Used to build the documentation for local preview - -|=== - - -## Running Tests - -To run all the tests, run: - -[source,bash] ----- -just test ----- - -The gradle test report is published to `build/reports/tests/test/index.html` - -### Execute tests for a specific class - -To run tests for a specific Class, `StepWrapperSpec` for example, run: - -[source,bash] ----- -just test '*.StepWrapperSpec' ----- - -### Code Coverage - -By default, JaCoCo code coverage is enabled when running test. - -Once executed, the JaCoCo coverage report can be found at: `build/reports/jacoco/test/html/index.html` - -To disable this, run: - -[source, bash] ----- -just --set coverage false test ----- - -## Linting - -This project uses https://github.com/diffplug/spotless[Spotless] and https://github.com/CodeNarc/CodeNarc[CodeNarc] to perform linting. The CodeNarc rule sets for `src/main` and `src/test` can be found in `config/codenarc/rules.groovy` and `config/codenarc/rulesTest.groovy`, respectively. - -Once executed, the reports can be found at `build/reports/codenarc/main.html` and `build/reports/codenarc/test.html`. - -To execute linting, run: - -[source,groovy] ----- -just lint ----- - -## Building the JPI - -To build the JPI, run: - -[source, bash] ----- -just jpi ----- - -Once built, the JPI will be located at `build/libs/templating-engine.jpi` - -## Building the Documentation - -This project uses https://antora.org/[Antora] to build the documentation. - -To build the documentation, run: - -[source, bash] ----- -just docs ----- - -Once built, the documentation can be viewed at `docs/html/index.html` - -### Customizing the documentation output directory - -The `docsDir` justfile variable configures the output directory. - -To modify the output directory, run: - -[source, bash] ----- -just --set docsDir some/other/directory docs ----- - -## Publishing JTE - -**If you have the permission**, you can cut a new release of JTE by running `just release `. - -For example: - -[source, bash] ----- -just release 2.0.4 ----- - -This will: - -1. create a `release/2.0.4` branch -2. update the version in the `build.gradle` -3. update the version in the `docs/antora.yml` -4. push those changes -5. create a `2.0.4` tag -6. publish the JPI - -[NOTE] -==== -Don't forget to go to the https://github.com/jenkinsci/templating-engine-plugin/releases[Releases Page] to officially release JTE with the current change log based off the most recent tag. -==== - -## Run a containerized Jenkins - -It is often helpful to run Jenkins in a container locally to test various scenarios with JTE during development. - -[source, bash] ----- -just run ----- - -With the default settings, this will expose jenkins on http://localhost:8080 - -### Change the container name - -[source, bash] ----- -just --set container someName run ----- - -### Change the port forwarding target - -[source, bash] ----- -just --set port 9000 run ----- - -### Pass arbitrary flags to the container - -Parameters passed to `just run` are sent as flags to the `docker run` command. - -[source, bash] ----- -just run -e SOMEVAR="some var" ----- - -### Mounting local libraries for testing - -Local directories can be configured as Git SCM library sources even if they do not have a remote repository. - -For example, if `~/local-libraries` is a directory containing a local git repository then to mount it to the container you would run: - -[source, bash] ----- -just run -v ~/local-libraries:/local-libraries ----- - -You could then configure a library source using the file protocol to specify the repository location at `file:///local-libraries` - -[TIP] -==== -When using this technique, changes to the libraries must be committed to be found. In a separate terminal, run: - -[source, bash] ----- -just watch ~/local-libraries ----- - -to automatically commit changes to the libraries. -==== diff --git a/NOTICE b/NOTICE deleted file mode 100644 index 84d070898..000000000 --- a/NOTICE +++ /dev/null @@ -1,5 +0,0 @@ -Jenkins Templating Engine -Copyright 2018 Booz Allen Hamilton - -This product includes software developed at -Booz Allen Hamilton (https://www.boozallen.com/). diff --git a/README.md b/README.md index ea2993d53..5d46e89a9 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,14 @@ [![Jenkins Plugin Installs](https://img.shields.io/jenkins/plugin/i/templating-engine.svg?color=blue)](https://plugins.jenkins.io/templating-engine) [![Gitter](https://badges.gitter.im/jenkinsci/templating-engine-plugin.svg)](https://gitter.im/jenkinsci/templating-engine-plugin) -
- -
+ + + + + +
+
+ +
+ 		**Table of Contents:** @@ -24,27 +29,22 @@ - [Squash Some Bugs](#squash-some-bugs) - [Feature Development](#feature-development) -## Overview - -The Jenkins Templating Engine (JTE) is a plugin originally created by [Booz Allen Hamilton](https://www.boozallen.com/) enabling pipeline templating and governance. - -Different teams are going to use different tools, but the flow of the pipeline is typically consistent. Having to maintain a Jenkinsfile in every source code repository introduces real challenges when scaling a DevOps pipeline across an organization: - -1. *Time*: Typical Jenkins Shared Libraries help to consolidate common pipeline code, but software teams should focus on where they provide business value: building their application. Jenkins can have a nontrivial learning curve and there's a desire to achieve economies of scale within an organization. -2. *Governance*: Having a Jenkinsfile in every repository makes it difficult, if not impossible, to ensure that every team is following an agreed upon business process to get code from developer's laptops out to users in production. Furthermore, developer's have access to this Jenkinsfile and could have permission to skip required quality or security gates. -3. *Maintainability*: Incorporating lessons learned into the pipeline over time becomes untenable when there are multiple pipeline definitions - it requires opening a Pull Request across each source code repository. +
-JTE aims to remove this friction by pulling the Jenkinsfile out of individual source code repositories and instead, creating tool-agnostic Pipeline Templates that can be reused across multiple teams. +## Overview -
- -
+The Jenkins Templating Engine (JTE) is a plugin originally created by [Booz Allen Hamilton](https://www.boozallen.com/) enabling pipeline templating and governance. -For the academic coders out there, one way to describe the Jenkins Templating Engine is an implementation of the Template Method Design Pattern for Jenkins pipelines. JTE essentially separates the business logic of a pipeline from the technical implementation. +JTE brings the [Template Method Design Pattern](https://refactoring.guru/design-patterns/template-method) to Jenkins pipelines. +Users can remove the Jenkinsfile from individual source code repositories in favor of a centralized, tool-agnostic [Pipeline Template](https://jenkinsci.github.io/templating-engine-plugin/2.5/concepts/pipeline-templates/). +This template provides the structure of the pipeline. -Templates define a workflow by calling *steps*. Steps are contributed by libraries. Instead of a Jenkinsfile in each source code repository, teams can now inherit a Pipeline Template (or choose a template from a Pipeline Catalog) and then *configure* the pipeline through a configuration file that specifies what libraries to load. Based on what libraries are loaded, the same Pipeline Template can be used to support an arbitrary combination of tools. +Pipeline functionality is provided by Library Steps. +For example, if the Pipeline Template references a `build()` step then the implementation of `build()` can be deferred to a user-developed library providing that step such as a Maven or Gradle library. -If your Pipeline Template is setup to build, test, scan, and deploy then it doesn't matter if you're using Docker, Maven, SonarQube, and Helm or NPM, Fortify, and S3: both pipelines can now be executed via the same Pipeline Template. +A hierarchical [Pipeline Configuration](https://jenkinsci.github.io/templating-engine-plugin/2.5/concepts/pipeline-configuration/) is used for each individual pipeline to determine which libraries to load (among other things). ## Learn More @@ -52,6 +52,7 @@ There are many resources available to help you get started: - [Documentation](https://jenkinsci.github.io/templating-engine-plugin) - **Presentations** + - [CDF Online Meetup](https://www.youtube.com/watch?v=FYLaoqn0pDE) - [Jenkins Online Meetup](https://www.youtube.com/watch?v=pz_kPpb9C1w&feature=youtu.be) - [JTE at KubeCon 2019](https://www.youtube.com/watch?v=OClSwxhsspA) - [Trusted Software Supply Chains with JTE](https://www.youtube.com/watch?v=TMxUAi3XXOg&list=PLj6h78yzYM2MGKo_LNRA-lhxlNXwiDJDT&index=5&t=0s) @@ -65,30 +66,16 @@ There are many ways to get involved. We look forward to hearing from you. ### Join the Conversation -JTE has a [channel](https://gitter.im/jenkinsci/templating-engine-plugin) in the Jenkins community's gitter space. It's a great place to ask questions or propose ideas for the future of JTE. +JTE has a [channel](https://gitter.im/jenkinsci/templating-engine-plugin) in the Jenkins community's gitter space. +It's a great place to ask questions or propose ideas for the future of JTE. ### Report a Bug or Request a Feature -Something not quite working right? Have a cool idea for how to make JTE better? Open an [Issue](https://github.com/jenkinsci/templating-engine-plugin/issues) on the JTE repository and let's get the conversation started. +Something not quite working right? Have a cool idea for how to make JTE better? +[Open an Issue](https://github.com/jenkinsci/templating-engine-plugin/issues/new/choose) on the JTE repository and let's get the conversation started. ### Contributions Welcome No contribution is too small - all are appreciated! -#### Documentation - -Documentation is crucial to the health of JTE as a framework. Please feel free to update the documentation to resolve typos, make an explanation more clear, or add a new page to explain a particular pattern or concept. - -JTE is the core engine that powers Booz Allen's open source DevSecOps capability, the Solutions Delivery Platform. To facilitate the aggregation of documentation, we leverage a documentation framework called [MkDocs](https://www.mkdocs.org/) along with the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme. Documentation for MkDocs is written in [Markdown](https://daringfireball.net/projects/markdown/basics). The documentation can be found in the ``docs`` directory. To view your changes locally, run ``just serve`` and then open ``0.0.0.0:8000`` in your browser. - -#### Unit Tests - -JTE is written in [Groovy](https://groovy-lang.org/) and Unit Tests for JTE are written using [Spock](http://spockframework.org/spock/docs/1.3/all_in_one.html). - -#### Squash Some Bugs - -Feel free to open a Pull Request that addresses one of the bugs outlined in an [Issue](https://github.com/jenkinsci/templating-engine-plugin/issues)! - -#### Feature Development - -New features are welcome. JTE strives to be an unopinionated framework for creating tool-agnostic Pipeline Templates. Some features are great ideas, but belong in a separate plugin or can be implemented through libraries. Because of this, it would be best to open an Issue to discuss the feature first so we can have a conversation about it to see if there's already a way to achieve the same functionality without bringing it into JTE's core. +Check out the [Contributing Section](https://jenkinsci.github.io/templating-engine-plugin/2.5/contributing/fork-based/) of the documentation to understand how to get started. \ No newline at end of file diff --git a/changelog.txt b/changelog.txt deleted file mode 100644 index d72ae1c46..000000000 --- a/changelog.txt +++ /dev/null @@ -1,36 +0,0 @@ -2019-06-19 Steven Terrana - * updated TemplateEntryPoint to set stash.useDefaultExcludes=false as .git was not being stashed -2019-05-30 Carlos OKieffe - * fsw-wrapper: implemented 'asType' on FileSystemWrapper to return SCMFileSystem -2019-05-23 Carlos OKieffe: - * fsw-factory-method: - * added job and scm factory methods to FileSystemWrapper - * moved JTEException to its own class - * aggregate-config branch: - * adding output of Pipeline.join changes - * archive aggregated pipeline_config.groovy for each build - * initial integration of TemplateLogger (logger branch) - * initial integration of TemplateConfigDsl serialization (print-config branch) - -2019-05-22 Steven Terrana: remove-facade - * replaced the Utils class with other classes and methods - -2019-05-20 Steven Terrana - * Add syntax checking to configuration file DSL parsing - -2019-05-15 Steven Terrana - * fix regression where libraries are not loaded with the most recent code. - -2019-04-26 Steven Terrana - * Internal refactoring to simplify library loading - * Add unit testing for Steps, Library Sources, and the Library Loader - * Adds helper methods hasStep() and getStep() to the TemplateBinding - -2019-04-12 Carlos OKieffe - * adding library sources base directory - -2019-04-11 Carlos OKieffe - * adding changelog.txt - -2019-04-10 Carlos OKieffe - * Updated ScmSpec to add more testing and test branches with '/' e.g., 'dev/main'