stlink's first badge is a licence badge for a different project, and its contributor guide names a branch that is not the default

The first badge is a licence badge for a different project

The first thing after the title in this README is a badge, and it points at somebody else's repository.

The image it loads is a raw file served from a repository with a different name and a different owner, under a branch that is not this project's. The two badges after it point at this project's latest release, and two CI workflow badges follow, so the first badge is the only one pointing elsewhere.

Everything else about the licence is consistent. The metadata records a three-clause BSD licence, the file is named with a Markdown extension at the repository root, and there is a section in the README that names the same licence and links that file.

So the terms are stated correctly in two places and misattributed in one. A badge is a convenient thing to copy, and copying it from a project you forked or were inspired by is exactly how this happens.

The title line above the badge is itself a third description. The heading calls it the open source version of the vendor's tools, the repository's own description calls it an open source programming toolset for the vendor's microcontrollers, and the licence section calls it a library and a set of tools. Three one-liners for one project, all defensible, none of them the one a badge would show.

Worth noting for anyone automating compliance: the badge image is a remote fetch, so a documentation page that mirrors this README will fetch it too.

The contributor guide says branch from develop while the default branch is testing

The contributing section gives a clear instruction, and the repository's own default branch is not the branch it names.

The instruction is to start new forks from the develop branch, and it adds that pull requests will go into that branch as well. The default branch is a third name.

So there are at least three branch names in play: the default, the branch contributions are forked from, and whatever the releases are cut from. The instruction is unambiguous about the first two, and the default is neither of them.

For a first-time contributor this is the kind of detail that costs a review cycle, because a pull request opened against the default branch goes somewhere other than where it was asked to go.

The versioning is semantic, and the change log is where the history is.

Two releases three and a half years apart, then two and a half more

The three visible releases are spread over five and a half years, and the gaps are not evenly sized.

The first is from April 2021. The second is from January 2024, which is two years and nine months later. The third is from October 2026, which is another two years and eight months after that. And the most recent push to the repository is six days after the third release.

So this is a project with a release every couple of years and pushes continuing after the newest tag.

That shape has consequences for anyone depending on it. A distribution package two years old, built from a release two years old, is running code that predates a lot of the fixes in the change log. And the version scheme is semantic, which is what makes those gaps legible: the minor component moves when something changes and the patch component when it is corrected.

The README points at the change log for recent changes and bug fixes, which is the right place to look, and points at two documents for the two things a user actually needs: the list of controller targets known to work, and the list of supported operating systems.

That second document is introduced with a sentence missing a word. A list of supported operating systems, the text says, can be found in the support document.

One platform has no binary and its builds are tested only in CI

The installation section covers three desktop systems, and the coverage is not symmetric.

On one, stand-alone archives are available, the project notes they are being provided again as of a named past release, and there is an architecture choice to make. The archive can go anywhere because it has no hardcoded paths, and the suggested locations are the two conventional program directories, one of which is the 32-bit one.

On the Unix systems, no stand-alone archive is offered. The recommendation is a package, and six distributions are linked, with the Debian and Ubuntu links pointing at the project's own releases. There is also a self-maintained package archive, and the reason it exists is spelled out: the packages in two of the named distributions differ from the project's own, so the project's is recommended instead, on the grounds that it lets the maintainers handle user-reported packaging problems directly and is not constrained by an external maintenance policy.

That is a good, honest paragraph about distribution politics, and it is the reason a user on those two systems should not install the distribution package and then file a bug upstream.

On the third platform, the text is two sentences and both are negative. The toolset has to be compiled from source, and no binaries are provided. And on two of the three platforms, the same sentence appears about build testing: it occurs in continuous integration only.

One hardware generation has been obsolete since 2019 and is still supported

The hardware section lists four generations of programmer board, and for each one it gives the transport layer and where the board is found.

Three of them use raw USB commands. The first uses a SCSI passthru transport over USB instead. That board is marked obsolete as of a specific day in 2019, with a note that this toolset continues to support it.

So the oldest supported generation is about seven years past the date the project itself marked it obsolete, and the README does not give a reason for retaining it. The first generation is fitted to the vendor's discovery boards, and the second and fourth to its evaluation and Nucleo boards. A board that ships on a development kit stays supported long after the standalone programmer is discontinued.

The fourth generation, STLINK-V3, is a family rather than a board, and the text names three product variants of it plus one variant that is fitted on-board.

And then the sentence that makes the list usable: at the user level there is no difference in handling or operation between these revisions. Which is the practical guarantee, since the transport detail is an implementation difference you would otherwise worry about.

One of the tools serves the programmer over TCP

The toolset is seven entries, and six of them are things you would expect. One queries the programmer and the chip. One manipulates flash. One records what happens during execution. One is a communication library, and one is an optional graphical interface.

The seventh is the interesting one: a tool that serves a local programmer over TCP, so that other tools can reach it remotely. That is a debug probe exposed as a network service, and the README describes it in one line with no further comment.

The line next to it is the reason this entry exists at all, and it is a nice piece of engineering: a GDB server, usable from an editor through a third-party debug plugin.

Which is also the case where access control matters, and the front page does not mention it: no credential, no bind address, no note about which interface it listens on. A local debug server is a network service with the privileges of a device programmer, and the documentation link in the front page is the place to look for how that is handled.

The tool list is also mixed in kind. Four are command-line utilities, one is a library, one is a GUI marked optional, and one is a network service, all in the same bulleted list with the same formatting.

The numbering rule that forbids a single character

One instruction in the contributing section is worth reproducing exactly, because it is the kind of rule that looks like nitpicking until you have hit it.

It says: never, ever use the hash character to count up points within a listing, because that character is exclusively reserved for referencing issues and pull requests, and doing so accidentally introduces false cross references into the project.

The mechanism is real. In the markup these files are written in, a hash followed by a number is a reference to that issue or pull request, and a renderer turns it into a link. So if a contributor numbers a list with that character, every item becomes a link to a pull request that does not exist, or worse, to one that does.

The rule is written in capitals and bold.

The same section pairs it with the rule that a feature needs a prior discussion and a bug fix does not. Two rules in one short list, one about the mechanics of the markup and one about process, and the mechanical one is the more emphatic.

Editorial conclusion

stlink fits anyone who owns one of these boards or a clone and wants to flash and debug it without the vendor's own software, and it is a poor fit on macOS unless you are willing to install a build toolchain. Three things to know. Windows gets stand-alone archives, Linux gets distribution or project deb packages, macOS gets source only, and the project says its builds on those platforms are tested in continuous integration rather than locally. The contributor instructions and the repository's own default branch disagree, so a first contribution needs the branch name checked before anything else. And the first badge on the front page is a licence badge for an unrelated project, so the terms to rely on are the section of the file and the licence file, not the image.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. README
4. Releases
5. stlink-org/stlink on GitHub