A real changelog is a small amount of work with an outsized return.

what it is for#

Deciding whether to upgrade. The single most common reason someone reads a changelog. They are on version 3.2, version 3.7 exists, and they want to know whether it is worth the risk.

Knowing what will break. The most important information you can provide, and the thing auto-generated release notes are worst at.

Debugging. "This started failing after we upgraded" — a good changelog turns that into "here is the change that caused it" in thirty seconds.

Finding out what exists. People discover features by reading changelogs. This is a real and underrated distribution channel for your own work.

why generated release notes are not enough#

A list of merged pull request titles has three problems.

It is written for the wrong audience. "Refactor connection handling" means something to the maintainer and nothing to the user. What changed for them?

It has no hierarchy. A breaking change and a typo fix appear as sibling bullets of equal weight.

It has no migration guidance. "Remove deprecated parse() method" tells you something broke. It does not tell you what to do about it.

the format#

Keep a Changelog is the established convention and it is good. The structure:

## [4.2.0] - 2026-07-22

### Breaking
- `Client.connect()` no longer accepts a positional timeout.
  Pass `timeout=` as a keyword.
      # before
      client.connect(host, 30)
      # after
      client.connect(host, timeout=30)

### Added
- `Client.ping()` for health checks without a full round trip (#412)
- Support for Unix domain sockets via `unix://` URLs (#398)

### Fixed
- Connections leaked when the handshake timed out (#405).
  If you saw file descriptor exhaustion under load, this was it.

### Deprecated
- `Client.legacy_mode` — will be removed in 5.0. Use `compatibility=`.

### Security
- Fixed a case where credentials could appear in debug logs (GHSA-xxxx-xxxx).
  Affects 4.0.0–4.1.3. Rotate credentials if debug logging was enabled.

the rules that make it useful#

Breaking changes first, always. That is what people are scanning for. Do not bury them under twelve feature bullets.

Include the migration. A breaking change without "do this instead" makes the reader open your source code. Two lines of before-and-after saves everyone time.

Describe the user-visible effect, not the implementation. Not "refactored the retry logic." Rather: "retries now use exponential backoff with jitter; if you relied on the previous fixed 1-second interval, set retry_delay=1.0."

Say who is affected. "If you use X, this changes for you. Otherwise nothing changes." Most readers can then stop reading, which is a service.

Link to the issue or pull request for anyone who wants detail. The changelog is a summary, not a substitute.

Date every release, in ISO format. Version numbers alone do not tell you whether you are two months or three years behind.

Write it as you go, not at release time. An Unreleased section at the top that each pull request adds to. Reconstructing a changelog from git history at release time is miserable and it is why changelogs get skipped.

the security section specifically#

If you fix a security issue, say so, with:

• Which versions are affected.
• What the impact is.
• Whether any action beyond upgrading is required.

That last one is the part that gets omitted and it is critical. "Upgrade to 4.2.0" is insufficient if credentials may have been exposed — the user also needs to rotate them, and they will not know unless you say so.

for internal projects#

The same file works for internal services, and the audience is your future self and the person who takes over the service.

The most valuable internal changelog entries are the ones that record a decision:

## 2026-07-14
- Switched from polling to webhooks for order status. Polling was
  costing ~40 requests/second against the vendor's rate limit and
  we were getting throttled during peaks.

Six months later, when someone asks why there is webhook infrastructure, the answer is in one place.

the return on investment#

Ten minutes per release. In exchange:

• Fewer support questions.
• Faster upgrades by your users, which means fewer people on old versions you have to support.
• Fewer surprised users after a breaking change.
• A record you can search when debugging.

There are not many ten-minute tasks with that profile.

This is not legal advice. It is the working map.

the permissive family#

MIT, BSD (2- and 3-clause), ISC, Apache 2.0.

What you must do: include the license text and the copyright notice with your distribution. That is essentially it.

What you may do: everything. Use it commercially, modify it, ship it in a closed product, sublicense it.

Apache 2.0 additionally: grants patent rights explicitly, and terminates those rights if you sue a contributor for patent infringement over the software. It also requires you to state significant changes you made.

That patent grant is why Apache 2.0 is preferred over MIT by legal departments at larger companies. MIT is silent on patents, which is not the same as safe.

In practice: include a NOTICES file or an attribution page listing your dependencies and their license texts. Generate it from your dependency tree. This is the entire compliance obligation for the permissive family and most products do not do it.

the weak copyleft family#

LGPL, MPL 2.0, EPL.

The rule: modifications to the licensed files must be released under the same license. Your own code that merely uses the library does not have to be.

MPL 2.0 is file-based, which is the cleanest formulation: if you modify a file that came under MPL, that file stays MPL. Everything else is yours.

LGPL is linking-based and the details matter. Dynamic linking is generally considered fine — the user must be able to replace the library. Static linking requires either providing object files so the user can relink, or releasing under compatible terms.

For most modern language ecosystems, "dynamic linking" does not map cleanly onto how code is actually distributed, and this is a genuine gray area. If you statically link LGPL code into a distributed binary, that is worth a real legal conversation.

In practice: MPL and EPL are unproblematic for most commercial use. LGPL is usually fine and deserves attention if you are shipping a compiled binary rather than running a service.

the strong copyleft family#

GPL v2, GPL v3.

The rule: if you distribute a work based on GPL code, the whole work must be under the GPL, and you must provide source.

The key question is what "distribute" means. Running GPL software on your server and letting users access it over a network is not distribution. This is why a very large amount of GPL software runs inside commercial SaaS products without obligation — Linux being the obvious example.

GPL v3 additionally: anti-tivoization (you must let users install modified versions on hardware you ship), and explicit patent provisions.

In practice: GPL dependencies in a hosted service are usually fine. GPL dependencies in software you ship to customers make your software GPL, which is usually not what you intended.

Know which of your dependencies are GPL. Most people do not.

the network copyleft family#

AGPL v3.

The rule: GPL, plus — if users interact with the software over a network, they must be able to get the source, including your modifications.

This closes the "SaaS loophole" deliberately. It is why many companies have a blanket policy prohibiting AGPL dependencies: the obligation is triggered by normal SaaS operation, and determining exactly how much of your system counts as "the software" is a question nobody wants to litigate.

In practice: if your company has a license policy, AGPL is almost certainly on the prohibited list. Check before you add the dependency, not after.

the source-available family#

BUSL, SSPL, Elastic License, various "fair source" licenses.

These are not open source licenses. They restrict commercial use, usually prohibiting offering the software as a service that competes with the licensor.

They exist because hyperscalers built managed services on open source projects without contributing back, and the projects had no recourse. That grievance is real.

In practice: read the actual text, every time. They differ substantially. Many convert to an open source license after a delay — BUSL typically becomes Apache 2.0 after four years — which means the version you are using today may become permissive before you care.

The specific question to answer: does your use case compete with the licensor's commercial offering? Usually the answer is obviously no and you are fine.

the practical program#

1. Generate an SBOM in CI. Every build, listing every dependency and its license. Tooling for this is mature in every major ecosystem.

2. Fail the build on prohibited licenses. Have a policy — usually: permissive fine, weak copyleft fine, GPL depends on whether you distribute, AGPL and source-available require review.

3. Generate the attribution file automatically. This is the actual compliance obligation for the licenses you are most likely to use, and generating it is a build step, not a project.

4. Check when you add, not when you ship. The cost of removing a dependency after it is embedded is enormous. The cost of checking at npm add time is zero.

the thing that trips people up#

License compatibility is not transitive intuition. You can use GPL code in a GPL project. You cannot use GPL code in an Apache-licensed library that others will embed in proprietary software — you have made your library effectively GPL, and your users will find out later.

If you publish a library, its license must be compatible with every dependency it pulls in. Check that specifically, because it is the mistake that is expensive to discover after adoption.

Five models. Each works. Each works for a specific kind of project.

1. donations and sponsorship#

Works for: developer-facing tools with a large individual user base and an identifiable maintainer.

Does not work for: libraries deep in a dependency tree, infrastructure nobody knows they use, anything without a personality attached.

The honest arithmetic: donation income correlates with visibility, not with importance. A well-marketed CLI tool with a charismatic maintainer will out-earn a critical cryptography library by a large multiple.

The corporate sponsorship version works better than individual donations and requires the maintainer to do sales, which most maintainers are bad at and hate.

2. foundation governance#

Works for: infrastructure that multiple large companies depend on and that none of them wants a competitor to control.

Does not work for: small projects. The overhead — governance, legal, trademark, process — is substantial, and a foundation with one project and no funded staff is just more paperwork.

The real value of a foundation is not money. It is neutrality: it makes a project safe for competitors to invest in together, which unlocks contribution that would not otherwise happen.

3. dual licensing#

Works for: libraries embedded in other products, where the copyleft obligation is genuinely inconvenient for commercial users.

Ship under a strong copyleft license, sell a commercial license to companies that cannot comply.

Does not work for: anything permissively licensed already (no leverage), anything not embedded (the obligation does not bite), or anything with a permissive competitor of similar quality.

Effective when it fits, and it produces a genuine tension: the license that makes the business work is the one that limits adoption.

4. open core#

Works for: products where enterprise features are genuinely separable from the core — SSO, audit logs, RBAC, compliance reporting, multi-tenancy.

Does not work for: libraries. There is no enterprise tier of a date-parsing library.

The failure mode is well documented: the line between core and commercial moves toward commercial over time, under revenue pressure, and the community that built your adoption watches features they use get moved behind the paywall.

If you do this, write down the line publicly, early, and honor it. "Anything that a single developer needs is open; anything that exists because you have a compliance department is commercial" is a defensible line. Moving it later costs more trust than the revenue is worth.

5. hosted service#

Works for: anything that is annoying to operate. Databases, search, queues, observability, CI.

Give away the software, sell the operation of it. This is the strongest model when it fits, because the value you sell — not having to run it — is real and continuous, and it does not require withholding anything.

The risk: a hyperscaler offers a managed version of your software, at scale, without contributing back. This has happened repeatedly and it is why the source- available licenses exist.

Those licenses solve the problem and cost you the open source designation, which costs you contributors, ecosystem inclusion, and some corporate adoption. It is a real trade with real costs on both sides, and the projects that made it mostly survived, which is the empirical answer to whether it works.

what actually kills projects#

Not the absence of a model. Three other things:

Solo maintainer burnout. One person, unpaid, receiving an unbounded stream of issues, feature requests, and entitled demands. Funding helps and does not fix it — the fix is more maintainers, which is a governance problem.

Success without support. A project that becomes critical infrastructure while its maintainer count stays at one. This is the most dangerous state and it is extremely common.

Corporate abandonment. A company open-sources a project, staffs it with employees, then reorganizes. The external community was never built because it was never needed. Now nobody knows the code.

what companies should do#

If your business depends on open source — and it does — the highest-leverage actions, in order:

1. Pay maintainers of your critical dependencies. Directly. Small amounts to many projects beat large amounts to a few.
2. Assign employee time to upstream contribution. More valuable than money and much rarer.
3. Do not send compliance questionnaires to volunteers. They owe you nothing and the license says so.
4. When you fix a bug in a vendored dependency, upstream it. The number of companies carrying private patches for bugs everyone has is enormous.

None of that requires a strategy document. It requires someone with budget deciding it matters, which is the actual bottleneck.

If you sell software into Europe, this is a real compliance project. If you maintain open source, the situation is more nuanced than either the panic or the reassurance suggests.

what it requires#

For products with digital elements — which is essentially any software or connected device sold commercially:

• Security by design and by default. Documented, with a risk assessment.
• No known exploitable vulnerabilities at time of release.
• Security updates for a support period, minimum five years or the expected product lifetime.
• A software bill of materials, maintained.
• Vulnerability disclosure process, published.
• Reporting of actively exploited vulnerabilities to the authorities within 24 hours of becoming aware, with follow-ups.
• CE marking and conformity assessment, the depth of which scales with product criticality.

That last set of obligations is the near-term one and the 24-hour clock is aggressive.

the open source position#

The Act was substantially amended after the initial draft caused an outcry from the open source community. The current position, roughly:

Not covered: software developed and supplied outside the course of a commercial activity. A maintainer publishing a library for free is not a manufacturer.

Covered: anyone who integrates that library into a commercial product. The obligation lands on the person selling the product, not on the upstream.

Partially covered: a new category of "open source software steward" — foundations and organizations that support the development of open source used in commercial products. Stewards have lighter-touch obligations around security policy and cooperation with authorities, not full manufacturer duties.

That structure is basically correct. The obligation should sit with the entity taking money for the product.

the part that will still hurt#

The obligation may not flow upstream legally, and it will flow upstream socially.

A company that must produce an SBOM, attest to no known exploitable vulnerabilities, and report incidents within 24 hours will start asking questions of its dependencies. Those questions arrive as GitHub issues addressed to unpaid maintainers:

• "Can you provide an SBOM for this library?"
• "What is your vulnerability disclosure policy?"
• "Can you commit to a support period?"
• "Please fill out this 40-question security questionnaire."

None of that is legally required of the maintainer. All of it will land in their inbox, and the maintainer of a two-thousand-line utility with a hundred million downloads is going to receive a lot of it.

The predictable outcome: some maintainers will comply out of conscientiousness and burn out. Some will add a line to their README saying they provide no warranties and will not respond to compliance requests, which is entirely their right. Some will archive the project.

what companies should actually do#

If you are the one with the obligation:

Do not send questionnaires upstream. Answer the questions yourself, about your product, using the information that is publicly available. That is what the regulation asks of you.

Generate the SBOM from your build, not by asking your dependencies. Tooling for this is mature.

Fund the projects you depend on. This is the actually effective response, it is cheap relative to compliance costs, and it is the only thing that improves the underlying situation. A maintainer with funding can respond to security reports; one without cannot.

Have a vendored fallback plan for critical dependencies with a single maintainer. If they archive the project, what do you do? Answer that before you need to.

the honest assessment#

The Act is trying to fix a real problem: consumer devices ship with known vulnerabilities and are never patched, and there has been no consequence for that. The obligations on manufacturers are reasonable and overdue.

The risk is that compliance cost lands disproportionately on small companies and that pressure lands informally on volunteers who owe nobody anything.

The mitigation for both is the same and it is boring: fund maintenance, generate your own compliance artifacts, and do not treat your dependencies' authors as your vendors. They are not, they never agreed to be, and the license says so explicitly.

The free tier is the story. This is a competitive move priced at zero.

what it does#

The familiar shape: a terminal agent with filesystem access, shell execution, git awareness, and web search. It reads a GEMINI.md for project-specific instructions. It supports MCP servers for extending its tool set.

npx https://github.com/google-gemini/gemini-cli

Sign in with a Google account and you are running. No API key, no billing setup, no credit card.

why free#

Two reasons, both strategic.

TPU economics. Google serves its own models on its own silicon in its own datacenters. The marginal cost of inference is genuinely lower for them than for anyone renting Nvidia capacity, and they can afford a free tier that competitors cannot match without eating a loss.

Developer mindshare is a leading indicator. The developers who adopt a tool today choose the platform their company standardizes on in two years. Google has lost that fight repeatedly — to AWS in cloud, to OpenAI in AI APIs — and this is a deliberate attempt to not lose it again.

the open source part#

Apache 2.0 on the whole client. That means you can fork it, audit it, run it against a different model endpoint if you rewire it, and inspect exactly what it sends where.

That last one matters more than people acknowledge. A terminal agent has filesystem and shell access. "What does this thing actually transmit" is a question a security team will ask, and "here is the source" is a much better answer than a data processing addendum.

I expect the open-source-ness to be adopted as table stakes. It is very hard to argue for a closed terminal agent when a competitive one is Apache 2.0.

the current state of the category#

By my count there are now four credible terminal-based coding agents from major vendors, plus several from startups, plus a healthy open-source contingent. All shipped within about six months.

They are converging fast on the same feature set: filesystem tools, shell, project instruction files, MCP support, permission prompts, git integration. The differences that remain:

• Model quality on long-horizon tasks, which is the real one.
• Context handling — how they decide what to read and when to compact.
• Permission ergonomics — how annoying the safety prompts are, which sounds trivial and determines whether people turn them off.
• Price, where Google just set an aggressive anchor.

the practical advice#

Try more than one on the same task. They differ more in practice than the feature lists suggest, and the differences show up on tasks that take twenty minutes, not on tasks that take two.

And whichever you use: sandbox it. Container, VM, or at minimum a dedicated user account without your production credentials in its environment. The tooling is good. The failure modes are still real, and "the agent ran a command I did not read carefully" is a bad way to learn that.