CONTRIBUTING.md

Contributing to Robo.js

Hey there! First and foremost, a big THANK YOU for showing interest in our project. Whether you're looking to contribute code or simply suggest features, we're glad to have you here! 💙

This document will guide you through the process of contributing to Robo.js.

Not a coder but got a neat idea? No worries!

➞ 📝 Suggest features by creating a GitHub Issue

➞ 🚀 Community: Join our Discord server

Remember, contributing to the core is different from making your own Robo or plugin. If you're looking for a starter guide:

➞ 📖 Tutorial: Making a "To-do" Robo

Setup

You just need a few tools to get started.

1. Node: Ensure you have Node 18 or newer. Older versions might work but are not tested.
2. Editor: We recommend VS Code, but GitHub Codespaces also works wonders.
3. Package Manager: We 💙 PNPM! Ensure you've got that. Simply run pnpm install after cloning the repo, and you're golden!

Monorepo

Now that you're all set up, let's dive into the monorepo structure.

Directories

• /docs: The documentation for Robo.js using Docusaurus.
• /packages: The core framework, plugins, and the create tool.
• /templates: Starter templates for Robo projects.

Plugins

Plugins under the packages directory are not much different from normal Robo projects. They follow the Robo.js File structure and use their README.md for documentation.

Templates

Templates are example Robo projects. They're a great way to get started with Robo.js and see what's possible. You can also use them to test your plugins as you're developing them!

These templates were created using the create-robo tool and can be used with the --template flag. For example:

npx create-robo my-robo --template starter-activity-typescript

Want to add your own? We'd love to see it! 🎉

Just make a PR with your template in the templates directory. We'll review it and add it to the list. Just make sure to include a README.md with instructions on how to use it and what it does.

Tools

We use a few tools to keep our code neat and tidy:

• Turborepo: A monorepo tool that makes managing multiple packages a breeze.
• ESLint: A linter that helps keep our code clean and consistent.
• Prettier: An opinionated code formatter that ensures our code is always formatted correctly.

Got the right VS Code plugins? These tools will be a lot of help getting PRs approved. Otherwise, just run pnpm lint to check your code before submitting.

Running

Ready to run the project?

1. Fork the repo: You'll need the entire monorepo to run the project.
2. Install dependencies: Run pnpm install to install all dependencies for the monorepo.
3. Build binaries: Run pnpm build:robo to build Robo.js. All other packages rely on it, even if you're not contributing to the core.
4. Build packages: Run pnpm build to build all packages. This will build all packages in the monorepo. You can also navigate to a specific package and run pnpm build there to build just that package.
5. Test it out: Whether you're working on the core or a plugin, you can test your changes by running pnpm dev in the package directory. You can then link your package to a Robo project using pnpm add <dirToPkg>.

If you'd like to auto rebuild, you can run pnpm dev instead of pnpm build. This will start a watcher that will rebuild your package whenever you make changes.

Plus, if you ran your test Robo in dev mode after that, it will automatically reload when you make changes!

Psst... If you need a Robo project to test your plugin, you can use the create-robo tool to create one, or use one of the templates in the /templates directory.

Submitting contributions

Ready to submit your changes? There's just a few things to keep in mind.

Commits

We highly encourage you to follow Conventional Commits. 📜

We follow Semantic Versioning (SemVer) for packages v1.0.0 and up. Under that? The second digit is for breaking changes and the third for everything else.

We also rely on Changesets for change management. Just run pnpm changeset and let the CLI guide you.

Starting a new package? Use 0.0.0 as your initial version and Changesets will handle the rest.

Linting

Please lint your code before submitting a PR. We use ESLint and Prettier to keep our code neat and uniform across the entire monorepo.

Seriously, just run pnpm lint and you're good to go!

Pull Requests

All set? Time to submit your PR!

• Ensure your PR is against the main branch.
• Give your PR a descriptive title and description.
• If your PR is a work in progress, add [WIP] to the title.
• If your PR is a fix for an existing issue, reference the issue in the description.
• Ensure you've made necessary changesets.

First-timer? Our CLA Assistant bot might pop up. Just sign the CLA and you're set!

What to contribute

Core

We always welcome contributions to the core: robo.js. Whether it's a bug fix, a new feature, or an enhancement, we're all ears!

Documentation

Documentation is a crucial part of Robo.js. If you find something that's unclear, outdated, or missing, feel free to submit a PR!

Plugins

Contribute to our official ones, enhance existing ones, or create your own!

For more, follow the plugin guide. Want a suggestion? A template project is a stellar way to test your plugin.

Ensure your plugin's robo.js version is consistent with your test project. For instance, if the Robo is at 0.10.0, ensure your plugin's devDependencies match or you'll run into issues with stateful APIs like Flashcore or State.

Templates

There's lots of awesome ways you can use Robo.js!

Templates are just example Robo projects. Starter templates are a great way to get started with Robo.js, and also a great way to see what's possible.

You can also use these to test your plugins as you're developing them! Just make sure to use a relative path. (e.g. npx robo add ../../my-plugin)

These templates are also used by the create-robo tool via the --template flag.

Contributors

A round of applause for our amazing contributors! 🎉

Pkmmte Xeleon ✨ 💻 🚧	Alexander ✨ 💻 🚧	Mouiz 📖	Matej Bošnjak 📖	Arnav K 💡 🔌 📖 💻	waru 💻	René 💻
Add your contributions