Comparing Open Source Projects
Compare projects against the user's actual domain and use case, not against a
context-free feature checklist. Treat current popularity, maintenance, and
licensing claims as evidence that must be checked rather than remembered.
Establish the comparison set
- When the user names exact candidates, compare those candidates. Do not add or
replace projects unless the user also asks for discovery.
- When the user supplies only a domain, define a transparent, representative
shortlist from current research. Search across project websites, canonical
forges, ecosystem directories, and credible roundups; then verify every
candidate against primary sources.
- State the inclusion criteria and important exclusions. Do not imply that a
shortlist is exhaustive.
- Ask one focused clarification when different interpretations of the domain
would materially change the candidates or recommendation. Otherwise state
reasonable assumptions in the report.
- If a named candidate is source-available, proprietary, abandoned, or not a
real match, retain it and explain the limitation rather than silently
substituting another project.
Collect comparable evidence
Use the same observation date and activity window for every project. Prefer
canonical project and repository sources; use secondary sources to discover
claims, not to establish them.
For every candidate, establish:
- Identity and fit: canonical project and repository, relevant edition or
component, supported use cases, deployment model, and important scope
boundaries.
- GitHub popularity: the star count of the canonical primary repository,
with its repository link and an as-of UTC date. Do not sum an organisation,
plugins, forks, or mirrors. If GitHub is not canonical, report
N/A and
identify any GitHub mirror separately. Stars measure attention, not quality.
- Maintenance: archived or deprecation state, date of the latest default-
branch commit, latest stable release, commit/release activity over a common
window, and evidence of issue or pull-request responsiveness where useful.
Distinguish active development, maintenance-only maturity, sporadic work,
inactivity, and insufficient evidence. Do not infer maintenance from stars
or from one recent automated commit.
- Licence: exact licence name and SPDX identifier when one exists, linked
to the governing licence text. Check multiple licences, exceptions,
component-specific terms, and community-versus-enterprise boundaries.
GitHub's detected licence is a discovery hint, not a substitute for reading
the repository's licence files. Clearly distinguish OSI/FSF-recognised open
source licences from source-available terms and avoid presenting the report
as legal advice.
- Decision factors: capabilities relevant to the requested domain,
maturity, integrations, operational burden, documentation/community, major
limitations, and the kinds of users for whom the project is or is not a
good fit.
Link factual claims to evidence. Use exact dates and counts where available,
and mark unknowns instead of estimating. Explain the basis of qualitative
maintenance ratings so a mature low-churn project is not automatically treated
as abandoned.
Analyse and recommend
Normalise terminology and compare like with like. Separate observations from
judgement, identify material evidence gaps, and explain trade-offs instead of
manufacturing a universal winner. Base recommendations on the user's stated
needs and call out when licensing or maintenance makes an otherwise strong
candidate unsuitable.
Use the mandatory high-level summary matrix for orientation. Add focused
matrices for distinct facets when they make a dense comparison easier to
understand. In matrices, apply accessible traffic-light ratings to cells where
relative strength or suitability can be judged fairly; retain plain text and
leave non-ordinal facts uncoloured. The reporting contract defines the rating
semantics and multi-matrix structure.
Produce the report
Read the HTML reporting contract completely before
writing the report. Use
the self-contained report template as the
structural and visual basis. The finished report must be written under
docs/research/ in the current Git repository and opened with the
repository-specific opener described in the reporting contract.
1---2name: comparing-open-source-projects3description: Researches and compares free and open source software projects in a supplied domain, using either user-named candidates or a discovered shortlist. Use when evaluating FOSS alternatives, comparing GitHub popularity, maintenance, licences, domain fit, trade-offs, or producing a linked HTML comparison report.4---56# Comparing Open Source Projects78Compare projects against the user's actual domain and use case, not against a9context-free feature checklist. Treat current popularity, maintenance, and10licensing claims as evidence that must be checked rather than remembered.1112## Establish the comparison set1314- When the user names exact candidates, compare those candidates. Do not add or15 replace projects unless the user also asks for discovery.16- When the user supplies only a domain, define a transparent, representative17 shortlist from current research. Search across project websites, canonical18 forges, ecosystem directories, and credible roundups; then verify every19 candidate against primary sources.20- State the inclusion criteria and important exclusions. Do not imply that a21 shortlist is exhaustive.22- Ask one focused clarification when different interpretations of the domain23 would materially change the candidates or recommendation. Otherwise state24 reasonable assumptions in the report.25- If a named candidate is source-available, proprietary, abandoned, or not a26 real match, retain it and explain the limitation rather than silently27 substituting another project.2829## Collect comparable evidence3031Use the same observation date and activity window for every project. Prefer32canonical project and repository sources; use secondary sources to discover33claims, not to establish them.3435For every candidate, establish:36371. **Identity and fit:** canonical project and repository, relevant edition or38 component, supported use cases, deployment model, and important scope39 boundaries.402. **GitHub popularity:** the star count of the canonical primary repository,41 with its repository link and an as-of UTC date. Do not sum an organisation,42 plugins, forks, or mirrors. If GitHub is not canonical, report `N/A` and43 identify any GitHub mirror separately. Stars measure attention, not quality.443. **Maintenance:** archived or deprecation state, date of the latest default-45 branch commit, latest stable release, commit/release activity over a common46 window, and evidence of issue or pull-request responsiveness where useful.47 Distinguish active development, maintenance-only maturity, sporadic work,48 inactivity, and insufficient evidence. Do not infer maintenance from stars49 or from one recent automated commit.504. **Licence:** exact licence name and SPDX identifier when one exists, linked51 to the governing licence text. Check multiple licences, exceptions,52 component-specific terms, and community-versus-enterprise boundaries.53 GitHub's detected licence is a discovery hint, not a substitute for reading54 the repository's licence files. Clearly distinguish OSI/FSF-recognised open55 source licences from source-available terms and avoid presenting the report56 as legal advice.575. **Decision factors:** capabilities relevant to the requested domain,58 maturity, integrations, operational burden, documentation/community, major59 limitations, and the kinds of users for whom the project is or is not a60 good fit.6162Link factual claims to evidence. Use exact dates and counts where available,63and mark unknowns instead of estimating. Explain the basis of qualitative64maintenance ratings so a mature low-churn project is not automatically treated65as abandoned.6667## Analyse and recommend6869Normalise terminology and compare like with like. Separate observations from70judgement, identify material evidence gaps, and explain trade-offs instead of71manufacturing a universal winner. Base recommendations on the user's stated72needs and call out when licensing or maintenance makes an otherwise strong73candidate unsuitable.7475Use the mandatory high-level summary matrix for orientation. Add focused76matrices for distinct facets when they make a dense comparison easier to77understand. In matrices, apply accessible traffic-light ratings to cells where78relative strength or suitability can be judged fairly; retain plain text and79leave non-ordinal facts uncoloured. The reporting contract defines the rating80semantics and multi-matrix structure.8182## Produce the report8384Read [the HTML reporting contract](references/reporting.md) completely before85writing the report. Use86[the self-contained report template](assets/report-template.html) as the87structural and visual basis. The finished report must be written under88`docs/research/` in the current Git repository and opened with the89repository-specific opener described in the reporting contract.
aspiers