Skip to content

Latest commit

 

History

History
90 lines (60 loc) · 4.63 KB

CONTRIBUTING.md

File metadata and controls

90 lines (60 loc) · 4.63 KB
Raw

Contributing Guide

New Contributors

Use the discussions tab at the top of the repository to:

  • Ask questions you're wondering about.
  • Share ideas.
  • Engage with other community members.

Feel free. But, please don't spam :p.

Keep in Mind

  1. Your contributions need not necessarily have to address any discovered issue. If you encounter any, feel free to add a fix through a PR, or create a new issue ticket.

  2. Use labels on your issues and PRs.

  3. Do not spam with lots of PRs with little changes.

  4. If you are addressing a bulk change, divide your commits across multiple PRs, and send them one at a time. The fewer the number of files addressed per PR, the better.

  5. Communicate effectively. Go straight to the point. Don't write unnecessary comments; don't be over-apologetic. Every single contribution is welcome, as long as it doesn't spam or distract the flow.

  6. Write useful, brief commit messages. Add commit descriptions if necessary. PR name should speak about what it is addressing and not the issue. In case a PR fixes an issue, use fixes #ticketno or closes #ticketno in the PR's comment. Briefly explain what your PR is doing.

  7. Always test your changes extensively before creating a PR. There's no sense in merging broken code. If a PR is a work in progress (WIP), convert it to draft. It'll let the maintainers know it isn't ready for merging.

  8. Read and revise the concepts about programming constructs you're dealing with. You must be clear about the behavior of the language or compiler/transpiler. See JavaScript docs and TypeScript docs.

  9. If you have a question, do a web search first. If you don't find any satisfactory answer, then ask it in a comment. If it is a general question about Music Blocks, please use the new discussions tab on top the the repository, or the Sugar-dev Devel <sugar-devel@lists.sugarlabs.org> mailing list. Don't ask silly questions (unless you don't know it is silly ;p) before searching it on the web.

Code Quality Notes

  1. Sticking to TypeScript conventions, use camelCase for filenames (PascalCase for class files), CAPITALCASE for constants, camelCase for identifiers, and PascalCase for classes. Linting has been strictly configured. A super-linter is configured to lint check the files on a pull request. In fact, the TypeScript watcher or build will throw errors/warnings if there are linting problems. This has been done to maintain code quality.

  2. If a PR is addressing an issue, prefix the branch name with the issue number. For example, say a PR is addressing issue 100, a branch name could be 100-patch-foobar.

  3. Meaningfully separate code across commits. Don't create arbitrary commits. In case it gets dirty, please do an interactive rebase with squash and reword to improve.

  4. Follow conventional commit messages specification to help issue tracking. More often than not, take time to add meaningful commit descriptions. However, add specificity by mentioning the component; prefer feat(mycomponent): [UI] add button over feat: add button, fix(mycomponent): use try-catch over fix: use try-catch, etc.

  5. At any point, when new components are created or existing components are modified, unit tests (passing) reflecting the changes need to be part of the PR before being reviewed.

  6. Two workflows -- a Continuous Integration (CI) and a Linter (Super Linter), have been configured. Each PR must pass the checks before being reviewed.

  7. For any new functions/methods or classes, add extensive TSDoc documentation.

  8. Each PR needs to have supporting unit tests covering all (or as much practical) use cases to qualify for review. In case testing is done via some non-standard method, adequate description of the method/s need/s to be specified in the PR body.

Checklist before Commits

  • Make sure there are no TypeScript warnings/errors. Run npm run check to verify.

  • Make sure there are no linting errors. Run npm run lint to verify.

  • Format code you've modified. Run npx prettier -w <file 1> <file 2> ....

  • Make sure the application builds successfully. Run npm run build to verify.

  • Add meaningful documentation to every new function/method/class/type added.

  • One commit must address only one concept. Do not add multiple unrelated changes in one commit.