diff --git a/README.md b/README.md index ded69de1..b155fad2 100644 --- a/README.md +++ b/README.md @@ -48,3 +48,7 @@ issue number in the pull request, but not the commit message. These practices al of ideas (Sugar Labs is a meritocracy). See [**full contributing guide**](./docs/CONTRIBUTING.md). + +## Beginner's guide + +See [Beginner's guide](./docs/BEGINNERS_GUIDE.md) diff --git a/docs/BEGINNERS_GUIDE.md b/docs/BEGINNERS_GUIDE.md new file mode 100644 index 00000000..2277ebc8 --- /dev/null +++ b/docs/BEGINNERS_GUIDE.md @@ -0,0 +1,89 @@ +# Beginner's Guide to Contributing to Musicblocks-v4 + +## Introduction + +Musicblocks-v4: Visual Programming Language & tools for musical/mathematical exploration in a fun way. + +## System Overview + +### Tech Stack + +- **Client-side Web Application**: + - **Written in TypeScript**: *TypeScript: JavaScript superset, adds static typing.* + - **UI Components with React**: *React: efficient JavaScript library for UI.* + - **Flexibility in UI**: Works with any JS library, framework, or DOM API.* + +### Bundling and Tooling + +- **Vite**: *Vite, the project bundler, speeds up development using native ES module imports.* +- **SCSS**: *SCSS (Sass) styles for a structured CSS approach.* + +#### Development Environment + +- **Node.js**: *The project needs Node.js for server-side JavaScript execution.* + +### Tooling + +- **ESLint**: *ESLint enforces code quality, ensuring consistent, high-quality standards.* +- **Docker**: *Docker: Ensures consistent, isolated environments for dev and deployment via containerization.* + +#### Testing and Quality Assurance + +- **Jest**: *Jest tests JavaScript, ensuring unit test coverage for code.* +- **Cypress**: *Cypress simulates user behavior for end-to-end testing, ensuring application functionality.* + +#### Contributing and Development Process + +- **GitHub Project Management**: + - The project leverages GitHub for task management via its Projects tab. + - Discussions tab is used for planning and tracking progress. + +- **Parallel Development Repository**: + - Development of the programming framework occurs in the musicblocks-v4-lib repository. + - The 'develop' branch and related feature branches serve as sources for updates. + - Issues tab in both repositories is used to track tasks and issues. + +## Resources to get started + +- **TypeScript**: + - [Docs](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html) + - [Video Tutorials](https://www.youtube.com/watch?v=30LWjhZzg50) + +- **React**: + - [Docs](https://react.dev/learn/typescript) + - [Video Tutorials](https://www.youtube.com/watch?v=FJDVKeh7RJI) + +- **Docker**: + - [Docs](https://docs.docker.com/) + - [Video Tutorial](https://www.youtube.com/watch?v=RqTEHSBrYFw) + +- **Jest**: + - [Doc](https://jestjs.io/docs/getting-started) + - [Video Tutorial](https://www.youtube.com/watch?v=ajiAl5UNzBU) + +- **Cypress**: + - [Docs](https://docs.cypress.io/guides/overview/why-cypress) + +## Tips for Effective Contributions + +- **Understand the Project**: +- **Explore Documentation**: Read project docs, README, and guidelines. +- **Review Code Structure**: Understand the code, align contributions with project design. +- **Follow Contribution Guidelines**: + - **Follow Coding Standards**: Meet formatting, naming, and project best practices. + - **Contribute Purposefully**: Align contributions with project goals. + +- **Write Clean and Readable Code**: + - **Modular Approach**: Break down code into logical, reusable components for readability. + - **Use Descriptive Naming**: Use meaningful names for variables, functions, and classes. + +- **Test Your Contributions**: + -**Test Your Code**: Write tests to validate changes; ensure they don't introduce bugs. + - **Check for Edge Cases**: Consider edge cases and handle them appropriately in your contributions. + +Join and communicate with other members on our community. +We communicate on Element. [Click here](https://app.element.io/#/room/#musicblocksdev:matrix.org) + +## Acknowledgment + +At Musicblocks-v4, every contribution, big or small, is valued.