On this page
When you need a sample pack
You need a sample pack only when a buyer's engineers ask, in writing and through Rightmark, to check a catalog entry against the code itself. Nothing in this guide is needed to list your code. That starts with Repo Check.
Every value you fill in comes from that request: which repositories, which track they belong to and who the recipient is. Rightmark passes you the request and tells you who your contact is. No Rightmark contact yet? Write to hello@rightmark.ai.
What a code sample pack is
A pack is real code. It holds whole repositories with their history, and every file is unchanged. Samples of other kinds of data are small and masked, as the sample pack guide for buyers describes. Code is different: an engineer has to build a repository and recount its figures, and that takes the whole repository. This is why the decision to send a pack is yours, for one recipient, under an NDA.
| Goes into the pack | Stays on your machine |
|---|---|
| One clean git repository per sample, with the branches and tags you chose | Your own repository, which the tool reads and never writes to |
| Placeholders where git recorded names and email addresses, unless you choose exact history | The map from real names to placeholders, and the key that made them |
| The description files: a table of the samples, a cover sheet and a manifest that a reviewer can check | Your word list and the private reports |
| Committed work that the copied branches and tags reach | Stashes, files git does not track, hooks, git's own logs and your git settings |
What you need
- Python and git. Nothing else to install: the tool is one file and uses only what ships with Python. The download below names the versions.
- macOS or Linux. On Windows, use WSL. The README inside the kit says what has been tested.
- For each repository: a clone on this machine, and the
share.jsonthat Repo Check wrote for it. Without one, you pass your own line count. - The written request, passed to you by Rightmark, that says which repositories go and who the recipient is.
Get the kit
The kit is one zip of text files: a start page, a reference for every command, the tool itself and a filled-in example made from invented repositories. Check its SHA-256 after you download it, and unpack it into a folder of its own.
Rightmark code sample pack kit
- File
- rightmark-sample-pack-kit-v0.3.0.zip
- Version
- 0.3.0,
- Size
- 313 KB
- SHA-256
- ea756761 91af24e6 075ceca6 f072cb28 ac39e32c 6c27b94a e6690552 ce71524c
- Needs
- Python 3.8 or newer and git 2.20 or newer
Check the download before you unpack it. On macOS:
shasum -a 256 rightmark-sample-pack-kit-v0.3.0.zipOn Linux:
sha256sum rightmark-sample-pack-kit-v0.3.0.zipWhat is in the zip
- START-HERE.md
- The steps on one page.
- README.md
- The reference: every command, every option and every message that stops a run.
- scripts/rightmark_sample_pack.py
- The tool. One file that needs Python and git, with nothing else to install.
- examples/
- The files you write and the files the tool writes, filled in, from invented repositories.
The steps
- Agree what goes in. With your Rightmark contact, pick the repositories the request asks for. The tool replaces the names and addresses that git recorded with placeholders unless you tell it otherwise.
- Write your word list. A plain text file with the names that must not appear in the pack: your company, your products, your clients and your domains, one per line.
- Run
prepareonce per repository. It copies the repository into the pack folder as a clean git repository and writes a private report for you. - Read the report. Revoke every real key it points at, and tell your Rightmark contact about each one: a revoked key is still text in the history. Then build and run the code from a fresh clone of the copy, so that your written steps are tested on what the reviewer gets.
- Describe it. Fill in the describe file of each repository and the cover sheet of the pack. Start with the
selectionline of the cover sheet: what the sample is meant to show. - Run
seal. It checks every repository, writes the description files and the zip, and unpacks the zip again to prove it is whole.
python3 scripts/rightmark_sample_pack.py prepare ~/sample-src/billing.git \
--name webdev-1 --pack ~/sample-pack \
--share ~/repo-check/billing/share.json --words ~/words.txt
python3 scripts/rightmark_sample_pack.py seal ~/sample-pack --check-only
python3 scripts/rightmark_sample_pack.py seal ~/sample-packseal --check-only writes nothing and lists what is left to do. The README inside the kit covers every option and every message that stops a run.
Names in the history: pseudonymous or exact
Git records a name and an email address for everyone who committed. Without --history, the copy is pseudonymous: those names and addresses are replaced by stable placeholders. Every commit keeps the same files and dates, and the same message text apart from the recorded names, addresses and commit ids replaced in it. That is what Rightmark recommends.
| What | Pseudonymous (the default) | Exact |
|---|---|---|
| Commits | The same files and dates at every commit, and the same message text apart from the recorded names, addresses and commit ids replaced in it | The originals, byte for byte |
| Commit ids | Change. A private map on your machine pairs each old id with its new one | Match your repository |
| Names and email addresses that git recorded | Replaced by stable placeholders, one per address | Go with the pack |
| Signatures | Left out, because they would no longer verify | Kept |
| Files | Unchanged | Unchanged |
The tool also looks for those names and addresses inside commit and tag messages and replaces the forms it recognizes. Then it reads the finished copy again and reports how many messages, and how many lines inside files, still hold one. A pseudonymous pack with any left is not sealed until you have changed them in your repository, or agreed with your Rightmark contact that they may stay.
Use --history exact only when the written request asks for unaltered history and you have agreed with your Rightmark contact that this recipient may see who you and your people are. An exact copy carries the name and email address of everyone who committed, and usually your company's email domain with them.
What the private report shows you
prepare writes one report per repository into a private folder next to the pack. Nothing in that folder is ever copied into the pack or the zip. Read all of it before you seal.
- What was copied and what stayed behind.
- The figures, counted the way a reviewer recounts them and set against your catalog entry, with one sentence for each figure that differs.
- People: how many placeholders were given, and where a recorded name or address still sits inside a file or a message.
- Each word from your list, by where it appears: branch and tag names, messages, recorded names and addresses, file paths and lines added.
- Possible secrets: how many places hold one and how many distinct values those are. Each value has a kind and a value id, never the value itself, and a list next to the report names every place.
- Files whose name usually means keys, and files whose name usually means exported records.
- What a reviewer will trip over: Git LFS pointers, submodules and links that point outside the repository.
Before anything leaves your machine
- You have decided to send this exact pack. Its pack id and its SHA-256 are on the receipt that
sealwrote. - An NDA with the recipient is in place.
- The recipient, the purpose and the way the pack travels are agreed with your Rightmark contact, and the route is one the NDA covers.
- Every real key the report pointed at is revoked, and your Rightmark contact knows about each one.
- You wrote who approved the pack, and the day, into the last two lines of the receipt. The receipt stays in your private folder.
Then give your Rightmark contact the pack id and the SHA-256 line that seal prints. Send nothing before every line above is true.
Limits, stated plainly
- The tool does not build, run or test anything. What you write under
verifiedis your own statement. - A pseudonymous copy changes no file. A name in a source file, a license header or an
AUTHORSfile is still there, and the report counts those lines. - A key that was committed once stays in the history of either kind of copy. Revoke it, or leave the repository out and tell your Rightmark contact.
- Git LFS content is not in a repository, so it is not in the pack. The pointer files are, and the pack says so. A submodule's code is not in the pack unless you prepare it as a dependency.
- Issues, pull request discussions and review comments live on your git host and are not in the pack.
- The README inside the kit lists the systems and versions the tool has been tested on.
Sources
- Rightmark: Trust and compliance
- Git: git-commit-tree Documentation (opens in a new tab)