Skip to content

Latest commit

 

History

History
115 lines (70 loc) · 3.31 KB

CONTRIBUTING.md

File metadata and controls

115 lines (70 loc) · 3.31 KB

Contribution Guidelines

Thanks for taking the time to contribute! 🎉👍!

Please follow the following guidelines when contributing to this project.

You will also have to sign the WüSpace Individual Contributor's License Agreement in order to contribute.

Contributing ADRs

What is an ADR?

An ADR is a design document that captures an important architectural or technical decision made along with its context and consequences.

Creating new ADRs

Open the project in the command line.

$ cd /path/to/project

Run the ./adr.sh script to create a new ADR.

$ ./adr.sh new "My ADR"

On Windows, use .\adr.cmd instead of ./adr.sh.

PS C:\path\to\project> .\adr.cmd new "My ADR"

Commit and push your changes to the main branch immediately to avoid naming collisions.

Updating existing ADRs

Depending on the state of the ADR you want to update, follow the steps below.

Proposed

Content Changes

Make your changes to the ADR and commit them to the main branch.

Accepting the ADR

To accept a proposed ADR, create a new branch titled accept-ADR-<adr-number>, and run:

$ ./adr.sh accept <adr-number>

or, if you're on Windows:

PS C:\path\to\project> .\adr.cmd accept <adr-number>

Then, create a Pull Request to merge the accept-ADR-<adr-number> branch into the main branch.

Accepted

If your change doesn't change the main content of the ADR, you can make changes on a separate branch and create a pull request to merge it into the main branch.

If your change also modifies the overall result / decision of the ADR, you have to create a new ADR that either amends the previous one or supersedes it. In this case (due to linking issues), the ADR has to be accepted immediately, which is why you need to create it in a separate branch.

Amending

If your change is a minor change that doesn't change the overall result / decision of the ADR, you can amend the ADR.

To do so, create a new branch titled amend-ADR-<adr-number>, and run:

$ ./adr.sh new "My ADR"
$ ./adr.sh link <new-adr-number> "Amends" <previous-adr-number> "Amended by"
$ ./adr.sh accept <new-adr-number>

or, if you're on Windows:

PS C:\path\to\project> .\adr.cmd new "My ADR"
PS C:\path\to\project> .\adr.cmd link <new-adr-number> "Amends" <previous-adr-number> "Amended by"
PS C:\path\to\project> .\adr.cmd accept <new-adr-number>

Then, create a Pull Request to merge the amend-ADR-<adr-number> branch into the main branch.

Superseding

If your change is a major change that changes the overall result / decision of the ADR, you can supersede the ADR.

To do so, create a new branch titled supersede-ADR-<adr-number>, and run:

$ ./adr.sh new -s <superseded-adr-number> "My ADR"
$ ./adr.sh accept <new-adr-number>

or, if you're on Windows:

PS C:\path\to\project> .\adr.cmd new -s <superseded-adr-number> "My ADR"
PS C:\path\to\project> .\adr.cmd accept <new-adr-number>

Then, create a Pull Request to merge the supersede-ADR-<adr-number> branch into the main branch.

Deprecated

Any deprecated ADR should only receive cosmetic changes. Any other changes should be applied to the ADR that supersedes the deprecated ADR.

Performing cosmetic changes works the same way as with accepted ADRs.