Contributing¶

We welcome all contributions to the project!

General guidelines about contributing to the SF-Operator can be found in this document.

Project repositories¶

The main repository of the project is hosted at softwarefactory-project.io.

The custom container images used by the SF-Operator are defined in the container-pipeline project and published on quay.io.

Use the git-review workflow to interact with these projects.

Repositories with the same name on GitHub are mirrors from softwarefactory-project.io, no pull request will be accepted there.

The MicroShift deployment Ansible role is hosted on GitHub. Pull Requests are welcome there.

Architectural Decision Records (ADRs)¶

Any large contribution aiming to modify or implement a functionality must be first validated by the community with an Architectural Decision Record (ADR).

For new ADRs, please use the template below as a boilerplate:

ADR template

template.md

---
status: {proposed | rejected | accepted | deprecated | … | superseded by ADR-000XXX (add link)}
date: {YYYY-MM-DD when the decision was last updated}
---

# {short title of solved problem and solution}

## Context and Problem Statement

{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story.
 You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}

## Considered Options

* {title of option 1}
* {title of option 2}
* {title of option 3}
* … <!-- numbers of options can vary -->

## Decision Outcome

Chosen option: "{title of option 1}", because
{justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.

<!-- This is an optional element. Feel free to remove. -->
### Consequences

* Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
* Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
* … <!-- numbers of consequences can vary -->


<!-- This is an optional element. Feel free to remove. -->
## Pros and Cons of the Options

### {title of option 1}

<!-- This is an optional element. Feel free to remove. -->
{example | description | pointer to more information | …}

* Good, because {argument a}
* Good, because {argument b}
<!-- use "neutral" if the given argument weights neither for good nor bad -->
* Neutral, because {argument c}
* Bad, because {argument d}
* … <!-- numbers of pros and cons can vary -->

### {title of other option}

{example | description | pointer to more information | …}

* Good, because {argument a}
* Good, because {argument b}
* Neutral, because {argument c}
* Bad, because {argument d}
* …

<!-- This is an optional element. Feel free to remove. -->
## More Information

{You might want to provide additional evidence/confidence for the decision outcome here and/or
 document the team agreement on the decision and/or
 define when this decision when and how the decision should be realized and if/when it should be re-visited and/or
 how the decision is validated.
 Links to other decisions and resources might appear here as well.}

Review Checklist¶

Before submitting a change or a patch chain for review, please consider the following checklist:

Are the commit messages clear and explanatory?
Do the changes need to be documented in the changelog?
Do the changes cover any required modification of the existing documentation? (see guidelines below)
Are the changes tested? We do not require unit testing but do expect functional testing coverage.

Documentation guidelines¶

The documentation is written in Markdown, as implemented by GitHub Pages. Please refer to this documentation to check what elements are supported.

Any change that implements a new feature or significantly changes an existing one must be reflected in the documentation, in the impacted section(s).

API Documentation¶

The API documentation is auto-generated with crd-ref-docs.

Running make or make build or make build-api-doc will update the API documentation if needed.

CLI Documentation¶

For now the CLI documentation must be updated by hand.