Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
156 lines (111 loc) · 5.34 KB

CONTRIBUTING.md

File metadata and controls

156 lines (111 loc) · 5.34 KB
Raw

Contributing to Awesome Math

Thank you for helping maintain this list. Read these rules before opening an issue or pull request.

Suggest a resource

Open a resource nomination issue before adding a new resource to the README. Use the nomination form and answer every required question.

A nomination should explain:

  • who the resource is for;
  • what it teaches or helps the reader do;
  • why it deserves a place in this list;
  • how it differs from similar entries;
  • who owns or maintains it;
  • whether it requires payment or registration;
  • any personal or financial connection between the proposer and the resource.

One nomination should cover one resource.

If a nomination is accepted, a maintainer may invite a pull request. Link the accepted nomination in the pull request description.

What belongs in this list

A resource should:

  • have a clear use in mathematics;
  • serve a clear audience;
  • provide enough depth, teaching value, authority, or technical value to justify a permanent entry;
  • add useful coverage or improve on resources already listed;
  • have a stable official page;
  • have a clear owner, author, institution, or maintainer;
  • include an accurate description of its value.

The proposer should have reviewed the resource. Search the README, open issues, closed issues, and pull requests before submitting it.

The subject structure is informed by the Mathematics Subject Classification 2020, with broader groups chosen for easier browsing. Suggest the section that will help readers find the resource. Maintainers may choose another section during review.

Resources we usually decline

We usually decline:

  • generic calculators and converters;
  • tutoring marketplaces;
  • SEO, affiliate, and lead-generation pages;
  • thin interfaces around a general AI model or computer algebra system;
  • printable worksheet and graph-paper sites;
  • small personal demonstrations with narrow use;
  • new projects with little evidence of quality or use;
  • bulk lists that have not received careful human review.

Past entries do not set a minimum standard for future entries. The list may contain older resources that no longer meet the current policy. Maintainers will review those entries over time.

Free and paid resources

We prefer free and open resources.

A paid resource may qualify when it is widely respected, unusually useful, and hard to replace. The entry must state any paywall, registration requirement, limited free plan, or other access restriction.

Talks, essays, and event archives

Talks, essays, seminars, and workshops may qualify when they offer lasting mathematical value. Prefer a stable series page or archive over an individual announcement.

A recurring series should have a useful archive or clear evidence of continued stewardship. A completed workshop should provide recordings, notes, proceedings, code, data, or another substantial record. Pages whose main use is registration or a current schedule are usually too temporary.

An individual post or case study needs a high bar. Claims about mathematical discovery or proof should link to a paper, formal proof, reproducible code, released data, or careful independent assessment. The description should make the verification method and the role of human review clear.

We usually decline company announcements without supporting technical material, live leaderboards, current model rankings, and posts whose value depends on recent news.

Self-authored resources and AI assistance

You may nominate your own work. State your relationship to it. Self-authored resources need strong evidence of quality, use, or independent recommendation.

You may use AI tools while preparing a contribution. Check every claim, link, and description yourself. You remain responsible for the contribution.

Entry format

Use this format:

- [Resource name](https://example.com/) - Why it is useful and who it is for.

Each entry should:

  • link to the official landing page when possible;
  • use a stable page instead of a version-specific PDF when both are available;
  • contain a short, factual description;
  • state the expected level when it is unclear;
  • state access restrictions;
  • end with a period.

Do not add format emojis to new entries.

Maintenance pull requests

You may open a pull request without a nomination issue for:

  • broken or redirected links;
  • removal of unavailable resources;
  • spelling and grammar fixes;
  • clearer descriptions;
  • category improvements;
  • repository policy or maintenance work.

Keep each pull request focused. Explain what changed and how you checked it.

Do not remove a resource based only on a timeout, 403 response, or other automated link-check result. Look for a current official page and confirm the resource status first.

Local checks

Before submitting a pull request, run:

python scripts/validate.py
npx --yes awesome-lint@2.3.0

Review

Inclusion is an editorial decision. A declined nomination may still be useful or well made. It may have too much overlap, too little evidence, or a scope that fits another list better.

Maintainers may edit descriptions, choose a different section, ask for more evidence, or close incomplete nominations.

After a nomination is declined, add substantial new evidence to the existing issue instead of opening another nomination. Repeated nominations without substantial changes may be closed as duplicates.