Identify software that materially shaped the work
Software belongs in the reference list when it performs a specialist role in collection, transformation, analysis, simulation or visualisation. That does not require a citation for every operating-system utility. Ask whether another researcher needs to identify the tool to understand the procedure, recognise a contributor or repeat the analysis. A statistical package, domain-specific parser, simulation library or custom analysis program often clears that threshold.
Citation and description do different jobs. The citation assigns credit and identifies an object; the methods record explains what you did with it. “Analysed in Python” does neither job well because it omits the packages, versions and configuration that produced the result. Conversely, placing every dependency in the bibliography can obscure the genuinely consequential components. Cite the substantive tools and preserve the full technical environment separately.
Look for the maintainers’ preferred citation
Check the project documentation, release page and repository for “Cite”, “Citation” or CITATION.cff. GitHub reads a CFF file in the repository root and can present its contents in common citation formats. Treat the output as structured source information, not an excuse to skip verification: make sure the displayed version corresponds to the code you ran. Some maintainers request both a software citation and a related paper. Include both only where each serves a distinct purpose.
If no recommendation exists, record the responsible developers or organisation, software title, exact release, year and persistent locator. A DOI is useful when a repository has archived a release. Software Heritage can identify archived source-code objects using SWHIDs. If the only evidence is a live repository, preserve a tag or full commit hash, repository URL and access date. A branch name alone is unstable because its pointer can move.
Release, commit and concept identifiers answer different questions
Choose the narrowest level that is both relevant and recoverable. If release 2.3 calculated the reported estimate, its version identifier is usually more useful than an identifier for the project across all releases. A concept DOI may be appropriate when discussing an evolving software family. Zenodo, for example, distinguishes the DOI for one version from a DOI representing all versions. Read the repository guidance rather than guessing from the identifier string.
A commit hash is precise within its repository but does not guarantee that the host will preserve the object indefinitely. Archiving a release adds managed metadata and a more durable retrieval route. For an online service that changes continuously, exact repetition may not be possible. In that case, state the provider, access date, visible service or model version, interface and key settings. Do not promise reproducibility where historical execution environments are unavailable.
Record the execution context in the method
Explain the role played by the software, its version, the modules used, consequential parameters and how outputs were checked. A scripted workflow benefits from a lockfile or dependency list, interpreter version, start command and random-seed record where relevant. A graphical workflow needs the selected filters, dialogue options and export settings. This separates your analytical choices from program defaults that might change later.
If you altered someone else’s code, identify the upstream release and your modifications separately. A fork with local patches is not the same object as the original package. Preserve a diff or archive your derived version where licensing, confidentiality and institutional policy permit. Attribution does not override the licence: permission to distribute, scholarly credit and methodological transparency are separate checks.
Make project code citable without exposing secrets
Give original analysis code a meaningful title, release number and README that states its purpose, prerequisites, entry point and expected output. A CITATION.cff record can hold creator names, ORCIDs, release date, version and DOI in a machine-readable form. Before depositing anything publicly, remove credentials, personal information, private server paths and third-party files you are not entitled to redistribute.
When open publication is impossible, the code can still have a stable identity. Use an institutional archive or controlled location, an internal version and a checksum, and state the conditions under which it may be inspected. “Available on request” is fragile when the responsible person later moves institution. A documented custody route and an honest list of withheld components are stronger evidence.
Five checks before you submit
- Does the cited release match logs, generated output or the environment file?
- Does the DOI or SWHID resolve to the exact object described?
- Have you respected a preferred citation while checking it against actual use?
- Can the methods record explain parameters, dependencies and local changes?
- If both software and paper are cited, does each support a separate claim?