Solutions Delivery Platform

Create A New Library

This page will outline the steps for adding a new SDP library that’s ready for others to consume and contribute to.

Ask yourself some questions

Does the library already exist? :)
Could this functionality be added to an existing library?
Is this library going to be usable by anyone else that wants to use this tool?

If the library doesn’t already exist, doesn’t make sense as an addition to an existing library, and represents a usecase that will be applicable outside of your current situation then it’s likely a good candidate for contribution!

Fork the SDP Libraries repository

This project follows a standard Fork Contribution Model, so if you havent, go ahead and fork the SDP Pipeline Libraries Repository.

Determine a name for the library

A library’s name is determined by the name of the directory that’s going to contain the implemented steps.
The name should be all lowercase, snake_case, and the same as the tool or process being integrated.
Of course, ensure this tool has

# from the root of the repository
mkdir libraries/<name_of_new_library>

Implement the library’s steps

Go on over to JTE’s Library Development documentation to learn how to create libraries.

There are a few conventions the SDP Pipeline Libraries have adopted, outlined below:

Check SDP library’s helper methods

The SDP library exists to implement common functionality required by the other libraries. It’s worthwhile to see if any of those steps are going to be useful to you during library development.

Add an SDP Pipeline Image (if necessary)

The SDP Pipeline Libraries try to install as few plugins on the Jenkins instance and as few tools on the underlying infrastructure as possible. We run portions of the pipeline inside container images, leveraging them as runtime pipeline environments. The existing container images used for this purpose can be found in the SDP Pipeline Images repository.

If your library requires runtime dependencies, like a CLI, capture them in a container image and open a PR to the SDP Pipeline Images repository.

In your step implementations, the image that is to be used should be overridable but default to the image hosted via GitHub Package Registry on the SDP Pipeline Images repository.

If your library requires runtime dependencies, your new library will not be accepted until the required image has been merged and published to the SDP Pipeline Images repository.

Add documentation for the library

Create the documentation page

Libraries are required a documentation page to be accepted.

To keep the library documentation consistent, copy the templated documentation page as a starting point to fill in:

= <Name of your Library>

< overview of the library and any links to background context >

== Steps Contributed

.Steps
|===
| *Step* | *Description*

| ``library_step_name1()``
| description of library_step_name1

|===

== Library Configuration Options

.Configuration Options
|===
| *Field* | *Description* | *Default Value*

| <example configuration field>
| <example description of the field>
| <default value, leave blank if no default value>

|===


[source,groovy]
----
libraries{
  /*
    replace this comment with an example configuration of the library
  */
}
----

== Results

// if images are required, create a new directory: docs/modules/ROOT/images/<library_name>

< a description of how the results are captured in the pipeline >
< if there are multiple artifacts generated, create H3s to describe the artifact and optionally an image

=== < artifact 1 >

// image:<library_name>/<picture>.jpg

== External Dependencies

< this is an optional block to be populated if the library has external dependencies like internet access, or network access to a persistently deployed tool outside of Jenkins >

== Troubleshooting

< keep this section and leave it empty.  to be filled in with frequently encountered issues or questions >

You can either:

copy and paste the above code snippet into docs/modules/ROOT/pages/libraries/<library_name>.adoc
run cp docs/modules/ROOT/examples/library_doc_template.adoc docs/modules/ROOT/pages/libraries/<library_name>.adoc

Add the library to nav.adoc

Antora is used to build the documentation. Antora leverages nav.adoc files to specify the page tree. Add the new library under the .Libraries header in docs/modules/ROOT/nav.adoc alphabetically.

Update the landing page libraries table

The landing page for the SDP Pipeline Libraries has a table that outlines each library and a high-level description of the library. Update this table in docs/modules/ROOT/pages/index.adoc.

Preview your documentation

You can run make docs at the root of the repository to build the documentation as static HTML. You can either open docs/html/index.html or run an nginx container locally to view the docs:

make docs
docker run --name docs -v $(pwd)/docs/html:/usr/share/nginx/html -e "NGINX_HOST=localhost" -p 80:80 -d nginx
# docs now viewable on http://localhost

Add unit tests

It’s highly encouraged that unit tests be written for the library.

Create a subdirectory under test named after the library: test/<library_name>
Read the Unit Testing Documentation
Write some tests for your steps

Add a library configuration file

To help prevent configuration errors, you can also validate the library parameters.

Open a Pull Request

The library is now done! At this point you should have:

A new library with steps implemented using the SDP library’s helpers if necessary
A new SDP Pipeline Image corresponding to the new library for its runtime dependencies
Documentation for the library
Unit tests for the library
A strategy for validating the library’s configuration parameters

These will all be confirmed during PR review.

Overview

The A11y Machine