documentation/docs/guides-concepts/contributing/index.md
We follow a code of conduct when participating in the community. Please read it before you make any contributions.
:::simple Requirements
:::
If your environment is ready, you can fork the Refine repository and clone it to your local machine.
After you fork the Refine repository, you need to clone it to your local machine. Instead of using the refinedev/refine repository, it's recommended to use your fork. This way, you can push your changes to your fork and create a pull request from there.
git clone https://github.com/refinedev/refine.git
After you clone the repository, you need to install the dependencies. We use pnpm as package manager with workspaces feature. You can run the following command to install, link dependencies and build packages:
pnpm install
If you don't want to wait for building packages, you can use
pnpm install --ignore-scripts
You can use pnpm build command with --scope flag to build packages & examples.
pnpm build --scope @refinedev/antd --scope base-antd
pnpm dev --scope @refinedev/antd --scope base-antd
After running this command, you should see the packages and examples you've started in watch mode. You can now make changes in any of them and see the results in the browser.
If you make a change in the @refinedev/antd package, you will see that right after the compilation, the base-antd example will re-compile and you will see the changes in the browser.
Navigate to the folder and run the following command:
cd packages/core
pnpm add my-new-dep
Just like the dev command, we can use the test command to run tests for the packages and examples we're working on.
pnpm test -- --scope @refinedev/antd
:::simple Good to know
:::
Refine documentation is built with Docusaurus. Documentation is handled separately from Lerna, so you need to install the dependencies and start the documentation separately.
cd documentation
pnpm install
pnpm dev:docs
:::simple Documentation Scripts
You can also use pnpm dev:blog to start the blog section of the documentation.
dev:docs and dev:blog scripts start a portion of the documentation and skips the unnecessary parts to speed up the development process such as type and props table generation, checklist generation, etc. If you want to start the documentation with all the features, you can use pnpm dev command.
To create a production build of the documentation, you can use pnpm build command. Then, you can use pnpm serve command to serve the production build in your local machine.
:::
We're using Codesandbox's Sandpack to provide live previews and code editors in our documentation. We've created a custom <Sandpack /> component to make it easier to use with Refine and provided some predefined configurations for the most common use cases.
Check out the example usage of <Sandpack /> in Core API's useForm hook documentation:
Refine is a monorepo with multiple packages and examples. To make sure we're keeping things clean and in order, we're using couple of tools to enforce a good development experience.
We are using biome for linting & formatting across the repository.
We suggest using biome VSCode extension to handle linting & formatting on your local environment to avoid unexpected failures on CI.
Since biome doesn't have markdown support yet, we are using prettier to format markdown files.
Commit messages are essential to keep everything clear in our development process. We use conventional commits to keep our commit messages consistent and easy to understand.
We're expecting to see proper commit messages with the following format:
<type>(optional scope): <description>
An example commit message:
feat(core): add useAwesome hook
:::simple Good to know
We're using commitlint to enforce conventional commits. If you don't follow the conventional commit format, you will see an error message when you try to commit your changes or a Github action will fail when you create a pull request.
:::
To manage our releases, changelogs and versioning, we're using Changesets and Changesets GitHub Action to automate the process. Changesets are designed to make your workflows easier, by allowing the person making contributions to make key decisions when they are making their contribution. Changesets hold two key bits of information: a version type (following semver), and change information to be added to a changelog.
Follow the steps below to create a changeset:
pnpm changeset
After you run this command, you will be asked couple of questions:
major/patch/minor according to your changeAfter you answer these questions, a changeset file will be created under .changeset directory. You can commit this file with your changes.
:::simple Good to know
.changeset directory.:::
Check out the following examples to see how changesets should be formatted:
---
"@refinedev/core": minor
---
feat: added x feature #ISSUE_ID
Now with x feature, you can do y.
Resolves #1234
or
---
"@refinedev/mantine": patch
---
fix: issue with x. #ISSUE_ID
We had an edge where it causes x issue to happen, now it's fixed.
Fixes #5678
After you commit your changes and create a changeset, you can push your changes to your fork and create a pull request. When you create a pull request, you will see a Github action that will run the tests and check if your changeset is valid. Our maintainers will review your changes in short time and merge your pull request if everything is good.
Our Pull Request template is designed to make sure you provide all the necessary information about your changes. Please make sure you fill the template with the required information.
We're looking forward to see your contributions! 🎉
Refine follows a monthly release cycle. We're releasing a new version every month with the changes we've made in that month. Unless there's a critical bugfix, we're not releasing a new version in the middle of the month. If your PR is approved and ready to be merged, it will be labeled as pr-ready and will be merged to the main branch with the next release.
Each approved PR will be included to a milestone, these milestones are used to track the progress of the monthly release.