Standard for Public Code

目次

  1. Requirements
  2. Why this is important
  3. What this does not do
  4. How to test
  5. Policy makers: what you need to do
  6. Management: what you need to do
  7. Developers and designers: what you need to do
  8. Further reading

到 GitHub 貢獻

Document codebase objectives

Requirements

  • The codebase MUST contain documentation of its objectives, like a mission and goal statement, that is understandable by developers and designers so that they can use or contribute to the codebase.
  • Codebase documentation SHOULD clearly describe the connections between policy objectives and codebase objectives.
  • Documenting the objectives of the codebase for the general public is OPTIONAL.

Why this is important

Documenting codebase objectives:

  • provides an easy way for people to decide whether this codebase, or one of its modules, is interesting for them now or in the future.
  • helps scope your own development.
  • clearly communicates to other stakeholders and contributors the purpose of the codebase and the modules of which it is composed.

What this does not do

  • Guarantee that the codebase achieves the stated objective(s).
  • Guarantee contributions to the codebase.
  • Prevent other codebases from attempting to achieve the same objectives.

How to test

  • Confirm that the codebase documentation includes the codebase objectives, mission or goal.
  • Check for descriptions of connections between policy objectives and codebase objectives.

Policy makers: what you need to do

  • Add the policy objectives to the codebase documentation, for example in the README.
  • Include relevant policies which impact the community, codebase, and development like value and ethics based policies, for example accessibility or equal opportunity.

Management: what you need to do

  • Add the organizational and business objectives to the codebase documentation, for example in the README.

Developers and designers: what you need to do

  • Add the technology and design objectives to the codebase documentation, for example in the README.

Further reading