Thanks for taking the time to read this! Whether you have an idea for a great feature, or have already made some improvements that you want to contribute, we really value your help in helping this project grow.
This guide should help you find answers to common questions:
- What is an SDP library?
- How can I contribute?
- What coding or style conventions should I follow?
- How is the documentation formatted?
- How do I test my changes?
- Where can I report a bug?
- Where can I make a feature suggestion?
- Where can I ask other questions?
Glad you asked! An SDP library is a collection of Jenkins pipeline steps that can be loaded and called using the Templating Engine plugin. These libraries are usually for using a certain tool (e.g. GitHub) in a software delivery pipeline. Check out our documentation on SDP libraries for more information, and browse this repository for examples.
Start by opening a GitHub Pull Request to the latest versioned branch
(e.g. 1.1) and filling out the template. We're incredibly grateful for
contributions, including
- new SDP libraries
- new features for existing SDP libraries
- improvements to existing SDP libraries
- bug fixes
If you're looking to contribute a feature suggestion, or want to help identify a bug, we appreciate that, too!
While we're still in the process of establishing a style guide, here are a few general conventions we've adopted:
- Groovy files that define pipeline steps use snake_case for method and variable names
- Indents are two (2) spaces.
- Pipeline steps should not take any arguments. Any variables should be set in the pipeline configuration
- Pipeline steps' code should be within a stage and a node
- Application source code is stored in a "workspace" stash.
- Unstash the workspace if using the source code
- Stash the workspace again to capture any changes used by other steps
A good general reference is Cloudbees Top 10 Best Practices for Jenkins Pipeline Plugin. For those unfamiliar with Groovy, Apache has a good Groovy Style Guide covering some of the general differences between Groovy and other languages. As a general note, the SDP uses scripted Jenkins pipeline syntax, as opposed to declarative pipeline syntax.
Our documentation, including this guide, is written in reStructuredText, which is a markup language similar to Markdown. If you're unfamiliar with reStructuredText, there are README.rst files in existing libraries for reference, and resources are available online.
We ask that the documentation include
- A general description of the library
- The pipeline steps the library contributes
- Information about any external configuration the library uses, including
- Any fields in the library block
- The datatype of those fields, and whether or not they're required
- Any other template primitives used (e.g. app_env's)
- Any external dependencies your library needs to work
- Jenkins credentials
- Content in the source code repository
- Web services and related setup
- Any Jenkins plugins or other libraries/steps the library depends on
Check out our documentation on writing unit tests.
One way is to create a GitHub issue. If you do, please
- include brief description
- list versions for Jenkins, the templating engine, and any plugins or other software that might be relevant
- describe how to recreate the issue
- give it the bug label, and any other relevant labels
You can also talk with us directly on our Gitter channel, and other Booz Allen Hamilton employees can reach us through the sdp-users slack channel.
While we ask that GitHub issues be limited to bugs and other defects, we welcome feature suggestions in our Gitter channel and internal sdp-users slack channel.
You can also submit a feature suggestion along with the actual feature in a pull request, which we appreciate immensely!
If you have questions that our documentation can't answer, you can reach us through the Gitter and Slack channels mentioned above.