README

👷 work in progress! See "Status" at bottom of README

Patchwatch will report on component patches applied to your projects. It aims to provide visibility on patches so you can see information like:

• Which consumed components (eg Composer or NPM packages) are we patching?
• Which projects are using which patches?
• What are the upstream issues related to each patch applied?
• What's the status of that upstream work? Where can we focus effort to be effective?
• Are our local projects applying the same versions of each patch?

With the information collated, you could view a report which shows the components you're modifying, the relevant upstream issues, and which of your local patches are using which patches. Cross-project visibility helps your team see what patches your projects need, while enriching data from upstream issues can help focus and inform your contribution / update efforts.

This is a tool with agencies or sets of sites in mind. If you're managing several similar project codebases (eg website codebases), and applying patches to consumed components as part of the build process, then it might interest you to know what similarities the patches used on those projects might have.

The problem

• We have multiple projects which share a common platform and components.
• When issues are identified, we contribute fixes to the platform and components via patches or MRs.
• Other projects may duplicate work identifying the same issues and discovering solutions.
• Sharing patches is good, actually.

The solution

• Capture information about our patch usage into a common repository.
• Identify commonalities in approach.
• Surface opportunities to move things forward.
• Automate this.

The implementation

1. Process patches from cweagans/composer-patches sources.
2. Search our common store of known patches for matches.
3. Create a new entry if there's no match.
4. Record the current project's usage of the patch in the found or created entry.

Some notes about this:

1. https://gist.github.com/xurizaemon/4b1539fd2bbf570bd8149a933ad8fcbe
2. What patches are we running?
3. Patchwatch progress report

Plans

Parsers

• cweagans/composer-patches patch file
• Drush make
• Composer lock (can read cweagans/composer-patches patches?)
• A directory of patches ...
• Node patch-package (eg Mahara patches, which is the above plus this filter)
• gem-patch?

Informers

Transformers? IDK - anyway enrich data about a patch URL so we can see eg Github/Gitlab/Drupal/... issue status based on patch details.

• Drupal
• Github
• Gitlab

Storage backends

• Gitlab
• Gist
• Directory

Outputs

• First quick prototype of this I arranged by patched component, then issue ID for each.
• Didn't sort except by order of seeing the projects.
• Could also group by project - but seeing several projects against one patch is interesting, esp where
• Markdown report like composer-lock-diff would be nice

More ...

• Support more parsers (eg patches for other projects)
• Support alternative backends for storage/discovery
• Suggest patches for consideration based on component use

Installation (developer edition)

1. git clone git@gitlab.com:xurizaemon/patchwatch.git
2. composer install
3. ./bin/patchwatch

The command will at some point be packaged as a .phar for easier consumption.

If you use Lando, there is a .lando.yml which has a known-good environment and some useful commands.

Testing

There is PHPUnit test coverage in the tests/src directory.

Contributing

This project uses semantic-release. Commit messages in Conventional Commits format are preferred, but don't stress, we can fix that up in the MR.

Status: WIP

This tool is at an early stage of development. Some simple commands are implemented to analyse patch sources. The structure of the codebase is likely to evolve. There is initial test coverage and input or contributions are welcome.

Pronunciation

Say it like pɔt͡ʃ wætʃ. Thankyou for reading this note!