Software · open source · CI/CD

Keep the upstream. Add your own.

Practice a small, reviewable patch and learn how to combine open-source updates with independently developed features.

See the result first

One upstream update. Your feature stays visible.

UpstreamPinned source
Your overlayIndependent patch
CIApply and verify
ReleaseReview evidence

This tiny Dojo-authored practice fixture changes a real program's output. It is not Mattermost, a paid feature, or a claim that a production integration has been run.

Before
Hello from upstream
After applying the patch
Hello from upstream + locally owned feature

Prefer configuration or a documented extension when it meets the need; patch only when the benefit justifies ongoing maintenance. Owning your own code can reduce vendor dependence, but every upgrade, security fix and compatibility check still has a cost.

Module 1 · try it

Apply one small feature

Download app.mjs and feature.patch into the same new, disposable folder. The practice instructions and MIT license notice are available too. You need Git and Node.js; check your organization's approved installation and tool permissions first.

Linux or macOS terminal

Open a terminal in that folder. The second line stops if the patch does not apply.

node app.mjs
git apply --check feature.patch && git apply feature.patch && node app.mjs
Windows PowerShell

Open PowerShell in the folder. This works with Windows PowerShell 5 and newer PowerShell versions.

node app.mjs
git apply --check feature.patch
if ($LASTEXITCODE -eq 0) {
  git apply feature.patch
  if ($LASTEXITCODE -eq 0) { node app.mjs }
}
Phone · ChatGPT, Claude or another assistant

Open both practice files and paste their contents, along with the prompt below, into an assistant you trust. Ask it to predict the before and after output and identify the changed line. Compare its answer to the result shown above. This is a reading exercise: the phone app does not apply the patch unless you separately provide a compatible environment and authorized tools. No plugin, MCP server or paid service is required.

The patch applies once to the original fixture. To repeat, download a fresh copy. Change the original message before applying it: the check should fail, and you must review the conflict instead of publishing a partial result.

Try the two-repository loop

In the same folder, also download two-repo-lab.sh. Read it before running it. In a Linux or macOS terminal, or Git Bash on Windows, run sh two-repo-lab.sh. It creates a temporary upstream repository and a separate patch repository, commits their submodule pins in a third repository, checks and applies the patch, and prints the before and after output. It removes the temporary repositories when it exits. Local file transport is enabled for those two practice commands only; global Git settings are not changed. No network access or Renovate installation is involved.

All ingredients

Outcome: a verifiable changed message. Harness and model: any assistant and model you can access, optional for the command-line exercise. Instructions and context: the prompt, original file, patch and your intended use. Roles: an inventory agent, implementation agent and independent reviewer can be separate people or agent sessions; you decide and verify. Tools: Git and Node.js for the computer exercise; a browser and assistant suffice to inspect it on a phone. No skill, MCP server, plugin or external API is required. Verification: run the original, check and apply the patch, run again, then deliberately test an incompatible change.

Select and copy the prompt. The Dojo does not send it to an assistant. Service availability, privacy terms and charges vary.

Module 2 · catalog before you build

Know exactly what you are adopting

Start with a product catalog: the outcome, owner, alternatives, support, security, deployment, cost and exit plan. Alongside it, make a license catalog for each source, binary, directory, dependency, plugin, asset and patch you actually use.

Download a blank product catalog · Download a blank license catalog · Open the decision record template · Study the OSS-first ladder

For each entry record its exact version or commit, source URL, artifact and paths, license and evidence, copyright notices, dependency and notice requirements, how you will use or distribute it, owner, review date and unresolved questions. A software bill of materials can help identify components; an automated scan is evidence to review, not a legal decision.

Module 3 · copyright and licenses

Open source is copyrighted too

Copyright protects eligible expression, including software. A license grants permissions under conditions. Copyleft uses copyright to preserve specified freedoms; it does not mean the author gave up copyright. Open-source licenses can be permissive or copyleft. A publicly readable repository is not necessarily open source, and no license is not permission to reuse code.

FamilyWhat to investigate
Permissive · MIT, Apache-2.0Copyright and license notices; Apache terms also address patents and notices.
File or library copyleft · MPL, LGPLThe exact covered files or library, modifications, distribution and conditions for combining code.
Strong copyleft · GPLWhen distribution triggers obligations, corresponding source and how the works are combined.
Network copyleft · AGPLModified network use as well as distribution; review the precise license and architecture.
Source available / commercialSpecific rights, subscriptions, allowed environments and restrictions. Read the actual terms; access to source alone is insufficient.

These are starting questions, not automatic classifications of a whole product. Licenses, exceptions, dependencies, linking, distribution, network use, contracts and jurisdiction matter. In enterprise or government work, involve the appropriate legal, procurement and security reviewers before adoption or release.

Learn from the US Copyright Office, Open Source Initiative FAQ, REUSE tutorial and SPDX specifications.

Module 4 · inspect a real product

Mattermost: one repository, multiple terms

At the pinned revision below, Mattermost's root licensing policy distinguishes vendor-produced compiled binaries from source builds and identifies exceptions for particular paths. The server/enterprise license states separate production subscription conditions. Read each relevant file, the notices and your deployment terms; do not treat an ee or enterprise directory as automatically reusable open-source code.

As a different, independently maintained example, the community Welcome Bot repository describes onboarding and channel-welcome features and declares Apache-2.0. Its README says it is community supported, not maintained by Mattermost. It is an example of an extension to investigate, not a verified replacement for any particular paid feature. Check the exact release, dependencies, server compatibility, security and terms before use. The Dojo has not installed or tested this integration.

Compare the source with Mattermost's official licensing FAQ and its community plugin releases. A third-party repository's license label alone does not establish ownership or grant rights to someone else's restricted code.

Practice: complete three catalog entries
  1. Record the exact Mattermost revision, source-build and vendor-binary distinction, and relevant paths.
  2. Record the enterprise directory's license and flag production rights for review instead of copying it into your overlay.
  3. Record the community plugin revision, license, dependency and compatibility questions, and what you would need to verify before installation.

Module 5 · maintain the stack

Renovate proposes. CI composes.

  1. Place approved upstream source and your independently authored customization in separate repositories. Pin both to reviewed commits. If you use a community extension, pin and review that separately too.
  2. Use Git submodules or another supported pinning approach. Renovate's Git submodule manager can propose updates to submodule references. Its documentation currently calls this manager beta and says it must be enabled. Install and authorize Renovate separately for your Git host.
  3. In an isolated, disposable CI checkout, fetch the pinned sources; check and apply your patch or build/install the reviewed extension using that project's documented method. Renovate does not automatically combine repositories or resolve conflicts.
  4. Fail closed on a patch conflict, failing tests, unresolved license findings or security review. Check features, regression tests, an SBOM and notices; review the update and release only after the gates pass. Preserve the previous artifact and record a rollback plan.

This optional renovate.json enables the documented beta submodule manager; it does not install Renovate or set up submodules:

{
  "extends": ["config:recommended"],
  "git-submodules": { "enabled": true }
}
Practice an upgrade and a blocked release

With app.mjs and feature.patch from Module 1 in a disposable folder, download upgrade-loop.sh into the same folder. Read it first, then run sh upgrade-loop.sh in a Linux or macOS terminal or Windows Git Bash. It needs Git, Node.js, tar and mktemp.

The script creates two local repositories and commits their pins. It builds an initial artifact, simulates a compatible upstream update and builds again, then simulates a conflicting update. The conflict stops the third build, and the script runs the previous good practice artifact. It removes its temporary repositories and files on exit. The pin updates are simulated with Git: this exercise does not install or run Renovate, contact a server or deploy a release. In a real pipeline, retain your complete release artifact and follow your own review and rollback process.

Pin your own two repositories

In a Linux or macOS terminal or Windows Git Bash, start from a clean composition repository and replace the placeholders with your own approved Git URLs and reviewed full commit IDs. The custom repository must contain your independently authored feature.patch at its root for the example below. Configure Git identity and any required repository access through your organization's approved method; do not put credentials in URLs. Commit the submodule pointers, then let Renovate propose changes for review.

# In your own clean composition repository, replace each placeholder.
git submodule add 'YOUR_REVIEWED_UPSTREAM_URL' vendor/upstream && \
git submodule add 'YOUR_REVIEWED_CUSTOM_REPO_URL' vendor/custom && \
git -C vendor/upstream checkout --detach 'YOUR_REVIEWED_UPSTREAM_COMMIT' && \
git -C vendor/custom checkout --detach 'YOUR_REVIEWED_CUSTOM_COMMIT' && \
git add .gitmodules vendor/upstream vendor/custom && \
git commit -m 'Pin upstream and customization'

Illustrative CI commands, not a ready-to-run Mattermost build. Adapt paths, pinned repositories and project-specific build and test commands after review:

# Example only: paths and project-specific tests belong to your project.
# Run in an isolated CI checkout after both repositories are pinned and reviewed.
set -eu
git submodule update --init
git -C vendor/upstream apply --check ../../vendor/custom/feature.patch && \
  git -C vendor/upstream apply ../../vendor/custom/feature.patch
# Stop on failure. Next run your project's build, tests, license review and security checks.

Pinning does not guarantee safety. Review bot permissions and proposed changes, verify provenance and license changes at each update, restrict untrusted build scripts and secrets, and apply your organization's approval policy. A separate repository does not automatically change copyright or copyleft obligations.

Study patch sets and forks · Follow the patch-fork loop lesson · Explore Renovate's Git reference datasource

Module 6 · verify and adapt

Can you keep it safe through an upgrade?

  1. List the before and after output and show that the patch applies to the original fixture.
  2. Change the original line and demonstrate that the patch check fails. Explain how your CI would stop a release and preserve the previous artifact.
  3. Fill out the catalog for the pinned Mattermost sources and community plugin. Identify unknown rights or compatibility; do not claim a review occurred.
  4. Choose configuration, an independently licensed extension, a small patch or a different product. Explain support cost, security, ownership and your exit plan.
Reveal a possible answer

If the source no longer matches the patch, stop the build, inspect the upstream change and update the patch with tests. For a real product, recheck licenses and provenance at the proposed revision. Keep the previous known-good artifact until the updated stack passes its technical and organizational review.

Try another Randori challenge · Take a kata into a mission · More katas