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: >-4 Researches and compares free and open source software projects in a supplied5 domain, using either user-named candidates or a discovered shortlist. Use6 when evaluating FOSS alternatives, comparing GitHub popularity, maintenance,7 licences, domain fit, trade-offs, or producing a linked HTML comparison8 report.9---1011# Comparing Open Source Projects1213Compare projects against the user's actual domain and use case, not against a14context-free feature checklist. Treat current popularity, maintenance, and15licensing claims as evidence that must be checked rather than remembered.1617## Establish the comparison set1819- When the user names exact candidates, compare those candidates. Do not add or20 replace projects unless the user also asks for discovery.21- When the user supplies only a domain, define a transparent, representative22 shortlist from current research. Search across project websites, canonical23 forges, ecosystem directories, and credible roundups; then verify every24 candidate against primary sources.25- State the inclusion criteria and important exclusions. Do not imply that a26 shortlist is exhaustive.27- Ask one focused clarification when different interpretations of the domain28 would materially change the candidates or recommendation. Otherwise state29 reasonable assumptions in the report.30- If a named candidate is source-available, proprietary, abandoned, or not a31 real match, retain it and explain the limitation rather than silently32 substituting another project.3334## Collect comparable evidence3536Use the same observation date and activity window for every project. Prefer37canonical project and repository sources; use secondary sources to discover38claims, not to establish them.3940For every candidate, establish:41421. **Identity and fit:** canonical project and repository, relevant edition or43 component, supported use cases, deployment model, and important scope44 boundaries.452. **GitHub popularity:** the star count of the canonical primary repository,46 with its repository link and an as-of UTC date. Do not sum an organisation,47 plugins, forks, or mirrors. If GitHub is not canonical, report `N/A` and48 identify any GitHub mirror separately. Stars measure attention, not quality.493. **Maintenance:** archived or deprecation state, date of the latest default-50 branch commit, latest stable release, commit/release activity over a common51 window, and evidence of issue or pull-request responsiveness where useful.52 Distinguish active development, maintenance-only maturity, sporadic work,53 inactivity, and insufficient evidence. Do not infer maintenance from stars54 or from one recent automated commit.554. **Licence:** exact licence name and SPDX identifier when one exists, linked56 to the governing licence text. Check multiple licences, exceptions,57 component-specific terms, and community-versus-enterprise boundaries.58 GitHub's detected licence is a discovery hint, not a substitute for reading59 the repository's licence files. Clearly distinguish OSI/FSF-recognised open60 source licences from source-available terms and avoid presenting the report61 as legal advice.625. **Decision factors:** capabilities relevant to the requested domain,63 maturity, integrations, operational burden, documentation/community, major64 limitations, and the kinds of users for whom the project is or is not a65 good fit.6667Link factual claims to evidence. Use exact dates and counts where available,68and mark unknowns instead of estimating. Explain the basis of qualitative69maintenance ratings so a mature low-churn project is not automatically treated70as abandoned.7172## Analyse and recommend7374Normalise terminology and compare like with like. Separate observations from75judgement, identify material evidence gaps, and explain trade-offs instead of76manufacturing a universal winner. Base recommendations on the user's stated77needs and call out when licensing or maintenance makes an otherwise strong78candidate unsuitable.7980Use the mandatory high-level summary matrix for orientation. Add focused81matrices for distinct facets when they make a dense comparison easier to82understand. In matrices, apply accessible traffic-light ratings to cells where83relative strength or suitability can be judged fairly; retain plain text and84leave non-ordinal facts uncoloured. The reporting contract defines the rating85semantics and multi-matrix structure.8687## Produce the report8889Read [the HTML reporting contract](references/reporting.md) completely before90writing the report. Use91[the self-contained report template](assets/report-template.html) as the92structural and visual basis. The finished report must be written under93`docs/research/` in the current Git repository and opened with the94repository-specific opener described in the reporting contract.
aspiers