DOCS: Create standard for format and structure of top-level project files across AboutCode repos

Open
#66 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
markdown
Domain
documentation

Research direction

Start by comparing the listed top-level files in dejacode, purldb, scancode.io, scancode-toolkit, and vulnerablecode. The issue names immediate targets: convert RELEASE.md in dejacode and scancode.io to rST, rename apache-2.0.LICENSE files to LICENSE, and document the standard for new AboutCode repos. Done means the file naming/format convention is applied or clearly documented, but the issue is old and cross-repo.

Written by the indexing model from the issue text.

Description

documentation

In most AboutCode repos we have a set of top-level project files including:

  • AUTHORS.rst
  • CHANGELOG.rst
  • CODE_OF_CONDUCT.rst
  • CONTRIBUTING.rst
  • LICENSE
  • NOTICE
  • README.rst
  • RELEASE.md (dejacode and scancode.io)
  • ROADMAP.rst

I looked at dejacode, purldb, scancode.io. scancode-toolkit and vulnerablecode as the primary examples

Although the GitHub norm is for the these files to be in markdown format we are using rST in most cases so the cost/effort to move to markdown does not make sense at this time.

For the LICENSE and NOTICE files we have a mixed bag:

  • dejacode: LICENSE file but no NOTICE (makes sense for AGPL-3.0 vs Apache-2.0)
  • purldb: NOTICE file plus apache-2.0.LICENSE and cc-by-sa-4.0.LICENSE
  • scancode.io: LICENSE and NOTICE files - this should be the pattern for all projects licensed under Apache-2.0)
  • scancode-tookit: NOTICE file plus apache-2.0.LICENSE and cc-by-4.0.LICENSE
  • vulnerablecode: NOTICE file plus apache-2.0.LICENSE and cc-by-sa-4.0.LICENSE

If you have a top-level file named LICENSE GitHub displays the license name in a "tab" at the top of the README. Using LICENSE as the file suffix does not seem to mean anything to GitHub.

The issue here is to standardize the format and structure of these files across repos and document it for new projects/repos. Some immediate action items include:

  • Convert RELEASE.md files to rST for dejacode and scancode.io (this should be easy since these are small chunks of text)
  • Rename apache-2.0.LICENSE files to LICENSE.
Dominant language
JavaScript
Stars
9
Forks
18
PR merge metrics
No merged PRs in 30d

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from aboutcode-org/www.aboutcode.org

All issues in aboutcode-org/www.aboutcode.org

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.