Thank you for considering contributing! There are many ways you can help.
File an issue if you think you’ve found a bug or would like to request a feature. Be sure to describe:
- How it can be reproduced
- What did you expect to happen?
- What actually happened?
- Version, platform, etc. if relevant
You can file all issues with Screwdriver in the screwdriver repo; please tag with appropriate Github labels whenever possible. We will update any issues we’re working on with a daily summary. To see what we’re currently working on, you can check out our digital scrum board in the Projects section of the Screwdriver API repo.
Submitting Pull Requests
Patches for fixes, features, and improvements are accepted through pull requests.
- Write good commit messages in the present tense (“Add X”, not “Added X”) with a short title, blank line, and bullet points if needed. Capitalize the first letter of the title and any bullet items. No punctuation in the title.
- Code must pass lint and style checks.
- All external methods must be documented. Add README docs and/or user documentation in our guide when appropriate.
- Include tests to improve coverage and prevent regressions.
- Squash changes into a single commit per feature/fix. Ask if you’re unsure how to discretize your work.
- Whenever possible, tag your pull request with appropriate Github labels.
Please ask before embarking on a large improvement so you’re not disappointed if it does not align with the goals of the project or owner(s).
Commit Message Format
We use semantic-release, which requires commit messages to be in this specific format:
|Type||feat (feature), fix (bug fix), docs (documentation), style (formatting, missing semi colons, …), refactor, test (when adding missing tests), chore (maintain)|
|Scope||anything that specifies the scope of the commit; can be blank, the issue number that your commit pertains to, or
|Subject||description of the commit|
Important: For any breaking changes that require a major version bump, add
BREAKING CHANGE somewhere in the commit title or message.
Examples commit titles:
- For a bug fix:
fix: Remove extra space
- For a breaking change:
feat(scm): Support new scm plugin. BREAKING CHANGE: github no longer works
Where to Contribute
Screwdriver has a modular architecture, and the various responsibilities are split up into separate repos.
Check out the architecture diagram to see the overall workflow of Continuous Delivery using Screwdriver. The next few sections will help lay out where different code repositories fit.
The screwdriver repo is the core of screwdriver, providing the API endpoints for everything that screwdriver does. The API is based on the hapijs framework and is implemented in node as a series of plugins.
- Build bookends allow a user to create setup and teardown steps for builds.
- The API can also send notifications to users. notifications-base is the base class for defining the behavior between screwdriver and notifications plugins, like email notifications.
The launcher performs step execution and housekeeping internal to build containers. This is written in Go and mounted into build containers as a binary.
- sd-step: A Shared Step allows people to use the same packages and commands in all build containers, regardless of build environment
- meta-cli: A Go-based CLI for reading/writing information from the metadata
An executor is used to manage build containers for any given job. Several implementations of executors have been created. All are designed to follow a common interface. Executor implementations are written in node:
- executor-base: Common interface
- executor-docker: Docker implementation
- executor-j5s: Jenkins implementation
- executor-k8s: Kubernetes implementation
- executor-k8s-vm: Kubernetes VM implementation
The executor router is a generic executor plugin that routes builds to a specified executor.
The object models provide the definition of the data that is saved in datastores (analogous to databases). This is done in two parts:
A datastore implementation is used as the interface between the API and a data storage mechanism. There are several implementations written in node around a common interface.
- datastore-base: Base class defining the interface for datastore implementations
- datastore-sequelize: MySQL, PostgreSQL, SQLite3, and MS SQL implementations
- datastore-dynamodb: DynamoDB implementation, with dynamic-dynamodb being used to create the datastore tables for it
The Artifact Store (not to be confused with the datastores mentioned above) is used for saving log outputs, shared steps, templates, test coverage, and any artifacts that are generated during a build. The log service is a Go tool for reading logs from the Launcher and uploading them to the store. The artifact-bookend is used for uploading artifacts to the store.
Source Code Management
An SCM implementation is used as the interface between the API and an SCM. There are several implementations written in nodejs around a common interface.
- scm-base: Common interface
- scm-bitbucket: Bitbucket implementation
- scm-github: Github implementation
Templates are snippets of predefined code that people can use to replace a job definition in their
screwdriver.yaml. A template contains a series of predefined steps along with a selected Docker image.
- templates: A repo for all build templates
- template-main: The CLI for validating and publishing job templates
- template-validator: A tool used by the API to validate a job template
Node module for validating and parsing user’s
The Ember-based user interface of Screwdriver.
- circuit-fuses: Wrapper to provide a node-circuitbreaker with callback interface
- client: Simple Go-based CLI for accessing the Screwdriver API
- gitversion: Go-based tool for updating git tags on a repo for a new version number
- keymbinatorial: Generates the unique combinations of key values by taking a single value from each keys array
- toolbox: Repository for handy Screwdriver-related scripts and other tools
- hashr: Wrapper module for generating ids based on a hash
Adding a New Screwdriver Repo
We have some tools to help start out new repos for screwdriver:
- generator-screwdriver: Yeoman generator that bootstraps new repos for screwdriver
- eslint-config-screwdriver: Our ESLint rules for node-based code. Included in each new repo as part of the bootstrap process
If you create a new repo, please come back and edit this page so that others can know where your repo fits in.
Screwdriver.cd Tests and Examples
The organization screwdriver-cd-test contains various example repos/screwdriver.yamls and acceptance tests for Screwdriver.cd.