Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README to-dos #213

Open
3 of 16 tasks
httpsmenahassan opened this issue Oct 10, 2023 · 0 comments
Open
3 of 16 tasks

README to-dos #213

httpsmenahassan opened this issue Oct 10, 2023 · 0 comments

Comments

@httpsmenahassan
Copy link
Contributor

httpsmenahassan commented Oct 10, 2023

I reviewed this repo's README against these specifications and outlined what's currently included and what needs to be added below.

When making any changes or updates, note that ideally we should stick to the exact section order shown below with additional sections added where it makes sense based on the maintainers' judgement.

Tasks

  • Title - The name of the component.
  • Badges - A set of badges that quickly let visitors review the health of the project. The badges section should contain at minimum the following badges:
    • License - Indicating the license of the repo.
    • Maintenance Status - One of maintained, deprecated, unsupported, experimental.
    • CI Status - The status of CI testing on the main branch.
    • Package Published Status - If the component is a library, then a badge indicating whether publishes to the relevant package index are passing. For example, has the latest version been successfully published to PyPI yor NPM?
  • Purpose - A paragraph or two summarizing the purpose of this component. This should be oriented towards people who are new to the Open edX project.
  • Getting Started - A section that details various aspects of getting started with this component. Some common use cases include, getting started with development or how to deploy this component.
    • Quickstart section doesn’t isn’t include npm install or nvm use
    • It also doesn’t mention that devstack should be running in the background. Not sure if we need that explicitly listed but if the goal of the README is to be as beginner friendly as possible, it’d be good to have that be clearly stated
  • Getting Help - A section to indicate where and how the user can get help with the component, including how they should go about reporting issues with the component. It should link to relevant docs as well as places where the users can get help from other humans.
  • Contributing - A section to indicate how new users can contribute to this component. This section should at the very least contain a link to the general How to Contribute documentation for the Open edX Project.
  • The level of contributions that the maintainer is willing to accept should also be clearly described here. Some possible values might be:
    • fixes only - no new features are being accepted at this point, but fixes and maintenance updates welcome.
    • new features accepted - please discuss your new ideas with the maintainers before you write code to increase the changes that features are accepted.
    • security only - no changes accepted except for security fixes.
  • Open edX Code of Conduct - A section that links to the Open edX Code of Conduct
  • People - A section that tells people how they can find the current maintainers of this component. Usually a link to the Backstage page for the component.
  • Reporting Security Issues - A link to the e-mail address where security issues can be reported.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant