Skip to content

Commit

Permalink
Update README.md contributor and release docs (#237)
Browse files Browse the repository at this point in the history 
* Update README.md contributor and release docs

A rough start.

* NOTICKET: Out of scope change, gitignore editors/OS.

* NOTICKET: Add semver and suggestion for release numbering.

* NOTICKET: Update README.md TOC.

npm install -g doctoc; doctoc README.md

* Update README.md grammar.

Co-authored-by: Andrew Berry <[email protected]>

* NOTICKET: Update README.md TOC.

npm install -g doctoc; doctoc README.md

* Update README.md

* Updated doctoc.

* Fixed Releases subsections.

* Update README.md

---------

Co-authored-by: Andrew Berry <[email protected]>
Co-authored-by: Dave Reid <[email protected]>
  • Loading branch information
@YesCT @deviantintegral @davereid
3 people authored Mar 26, 2024
1 parent c7bf250 commit 1cd4e04
Show file tree
Hide file tree
Showing 2 changed files with 100 additions and 34 deletions.
7 changes: 7 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,3 +14,10 @@ tests/fixtures/drainpipe-test-project/*
!.yarn/versions
.npmrc
lerna-debug.log

################
# Editors / OS #
################
.idea
.DS_Store
.vscode
127 changes: 93 additions & 34 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,30 +8,49 @@ for a Drupal site, including:
- Automated testing setup
- Integration with DDEV
- CI integration
---
* [Installation](#installation)
* [Database Updates](#database-updates)
* [.env support](#env-support)
* [SASS Compilation](#sass-compilation)
* [JavaScript Compilation](#javascript-compilation)
* [Testing](#testing)
+ [Static Tests](#static-tests)
+ [Functional Tests](#functional-tests)
- [PHPUnit](#phpunit)
- [Nightwatch](#nightwatch)
+ [Autofix](#autofix)
* [Hosting Provider Integration](#hosting-provider-integration)
+ [Generic](#generic)
+ [Pantheon](#pantheon)
* [GitHub Actions Integration](#github-actions-integration)
+ [Composer Lock Diff](#composer-lock-diff)
+ [Pantheon](#pantheon-1)
* [GitLab CI Integration](#gitlab-ci-integration)
+ [Composer Lock Diff](#composer-lock-diff-1)
+ [Pantheon](#pantheon-2)
* [Tugboat Integration](#tugboat)
* [Peer Review Guidelines for Automated Updates](#peer-review-guidelines-for-automated-updates)
---

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [Installation](#installation)
- [Binaries](#binaries)
- [Database Updates](#database-updates)
- [.env support](#env-support)
- [SASS Compilation](#sass-compilation)
- [Setup](#setup)
- [JavaScript Compilation](#javascript-compilation)
- [Setup](#setup-1)
- [Testing](#testing)
- [Static Tests](#static-tests)
- [Excluding Files from PHP_CodeSniffer](#excluding-files-from-php_codesniffer)
- [Functional Tests](#functional-tests)
- [PHPUnit](#phpunit)
- [Nightwatch](#nightwatch)
- [Autofix](#autofix)
- [Hosting Provider Integration](#hosting-provider-integration)
- [Generic](#generic)
- [Importing/Exporting Databases](#importingexporting-databases)
- [Snapshots](#snapshots)
- [Pantheon](#pantheon)
- [GitHub Actions Integration](#github-actions-integration)
- [Composer Lock Diff](#composer-lock-diff)
- [Pantheon](#pantheon-1)
- [GitLab CI Integration](#gitlab-ci-integration)
- [Composer Lock Diff](#composer-lock-diff-1)
- [Pantheon](#pantheon-2)
- [Tugboat](#tugboat)
- [Contributor Docs](#contributor-docs)
- [Peer Review Guidelines for Automated Updates](#peer-review-guidelines-for-automated-updates)
- [Handling Version Ranges](#handling-version-ranges)
- [Handling Test Failures](#handling-test-failures)
- [Conducting the Peer Review](#conducting-the-peer-review)
- [Releases](#releases)
- [drainpipe and drainpipe-dev release process](#drainpipe-and-drainpipe-dev-release-process)
- [NPM package release process](#npm-package-release-process)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Installation

```sh
Expand Down Expand Up @@ -629,13 +648,22 @@ php:
visualdiff:
```

## Peer Review Guidelines for Automated Updates
## Contributor Docs

This repo is public.

These are guidelines for conducting peer reviews on automated dependency update pull requests created by Renovate.
Please be careful to remove sensitive customer specifics when posting Issues or comments.

## Automated Testing with GitHub Actions
First time contributors need a maintainers approval for automated tests to run.
(This is so we aren't at risk of getting a big CI bill accidentally, or maliciously.)

### Overview
Peer Reviewing by looking at PR code changes is nice.

Testing PR code changes on real sites is extra beneficial.

### Peer Review Guidelines for Automated Updates

These are guidelines for conducting peer reviews on automated dependency update pull requests created by Renovate.

All automated updates submitted by Renovate undergo a series of automated tests via GitHub Actions. These tests are designed to ensure compatibility and stability with the new versions of dependencies.

Expand All @@ -645,23 +673,23 @@ All Renovate peer reviews regardless if they're a minor or patch release require
- Consider the implications of new features on the project's future development and maintenance.
2. All tests and checks must pass

### Handling Version Ranges
#### Handling Version Ranges

Some dependencies allow multiple versions, like `"drush/drush": "^10|^11|^12"`.
- Renovate will create pull requests when any of these versions get patch or minor releases.
- We **DO NOT** want to merge these, because it would pin these packages to a specific version.
Some dependencies allow multiple versions, like `"drush/drush": "^10|^11|^12"`.
- Renovate will create pull requests when any of these versions get patch or minor releases.
- We **DO NOT** want to merge these, because it would pin these packages to a specific version.
- We **DO** want to allow these pull requests to run checks. This will confirm that the latest version within the range Drainpipe supports is unlikely break builds.
- After all GitHub Action checks pass, leave a comment on the pull request stating such, close the pull request, and delete the branch.

### Handling Test Failures
#### Handling Test Failures

Occasionally, tests may fail due to transient issues or flakiness in the test suite. In such cases:

1. Verify the nature of the test failure to ensure it's not related to the dependency update.
2. If the failure seems unrelated to the update, re-run the GitHub Actions job to confirm if the issue persists.
3. Document any recurring flakiness or issues on the pull request then create a new issue linked to the pull request for further investigation.

## Conducting the Peer Review
### Conducting the Peer Review

1. **Review the Automated Update Pull Request (PR)**:
- Ensure the PR title and description clearly describe the update and its scope.
Expand All @@ -678,3 +706,34 @@ Occasionally, tests may fail due to transient issues or flakiness in the test su
5. **Final Decision**:
- For patch releases with all tests passing, proceed to merge the update.
- For minor point releases, after thorough review and consideration, decide whether to merge the update or request manual testing before merging.

### Releases

#### drainpipe and drainpipe-dev release process

When making a release, increase the version based on https://semver.org/

> MAJOR version when you make incompatible API changes
> MINOR version when you add functionality in a backward compatible manner
> PATCH version when you make backward compatible bug fixes
Specifically for drainpipe, when a new "check" is added, that might break builds in projects,
that would usually be a MINOR release, with a release note about the change.

Before making a new release, post in the lullabot internal #devops slack channel to coordinate with other maintainers.

1. Generate a GitHub release for drainpipe
1. Supply the correct tag based on the changes and semantic versioning standards.
2. Use the suggested release notes.
3. Set this release as latest and publish.
2. The release when published will automatically kick off a release of [drainpipe-dev](https://github.com/Lullabot/drainpipe) using the [DrainpipeDev GitHub workflow](https://github.com/Lullabot/drainpipe/actions/workflows/DrainpipeDev.ym). However this needs some manual followups:
1. This action ends up creating a branch in drainpipe-dev with the same name as the tag you just entered in the release.
2. Delete the branch that was created in drainpipe-dev.
3. Create a release with the same tag name in drainpipe-dev and in the release notes, just link to the drainpipe release that was made in step 1.

#### NPM package release process

To generate new NPM package releases:

1. Have the latest main branch checked out locally
2. Run `yarn learna publish`

0 comments on commit 1cd4e04

Please sign in to comment.