forked from refinedev/refine
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: development and contributing guides (refinedev#5384)
* docs(sandpack): fix theme issue in production * docs(contributing): rewrite contributing guide * docs(development): add development docs * docs(contributing): fix typo * docs(contributing): fix typo
- Loading branch information
Showing
12 changed files
with
625 additions
and
584 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
256 changes: 256 additions & 0 deletions
256
documentation/docs/guides-concepts/contributing/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,256 @@ | ||
| --- | ||
| title: Contributing | ||
| --- | ||
|
|
||
| We follow a [code of conduct](https://github.com/refinedev/refine/blob/master/CODE_OF_CONDUCT.md) when participating in the community. Please read it before you make any contributions. | ||
|
|
||
| - If you plan to work on an issue, mention so in the issue page before you start working on it. | ||
| - If you plan to work on a new feature, create an issue and discuss it with other community members/maintainers. | ||
| - Ask for help in our [community room](https://discord.gg/refine). | ||
|
|
||
| ## Ways to contribute | ||
|
|
||
| - **Stars on GitHub**: If you're a Refine user and enjoy using our platform, don't forget to star it on [GitHub](https://github.com/refinedev/refine)! 🌟 | ||
| - **Improve documentation**: Good documentation is imperative to the success of any project. You can make our documents the best they need to be by improving their quality or adding new ones. | ||
| - **Give feedback**: We're always looking for ways to make Refine better, please share how you use Refine, what features are missing and what is done good via [GitHub Discussions](https://github.com/refinedev/refine/discussions) or [Discord](http://discord.gg/refine). | ||
| - **Share Refine**: Help us reach people. Share [Refine repository](https://github.com/refinedev/refine) with everyone who can be interested. | ||
| - **Contribute to codebase**: your help is needed to make this project the best it can be! You could develop new features or fix [existing issues](https://github.com/refinedev/refine/issues) - every contribution will be welcomed with great pleasure! | ||
| - **Share your own integrations**: If you've created an integration for Refine, this can be a data provider, an auth provider, a UI integration or a routing integration, please share it with us! Refine's community has been growing rapidly and we're sure that your integration will be useful for many people. We'll be happy to add your integration to our [integrations page](https://refine.dev/integrations) along with the other community made integrations and share it with our community. | ||
|
|
||
| ## Setting Up Your Environment for Development | ||
|
|
||
| :::simple Requirements | ||
|
|
||
| - [Node.js](https://nodejs.org/en/) version 18 or higher | ||
| - [Git](https://git-scm.com/) and [GitHub](https://github.com) account | ||
| - [npm](https://www.npmjs.com/) version 7 or higher | ||
|
|
||
| ::: | ||
|
|
||
| If your environment is ready, you can [fork the Refine repository](https://github.com/refinedev/refine/fork) and clone it to your local machine. | ||
|
|
||
| ### Cloning the Repository | ||
|
|
||
| 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. | ||
|
|
||
| ```sh | ||
| git clone https://github.com/refinedev/refine.git | ||
| ``` | ||
|
|
||
| ### Installing dependencies | ||
|
|
||
| After you clone the repository, you need to install the dependencies. You can use your favorite package manager to do that. | ||
|
|
||
| <Tabs> | ||
|
|
||
| <TabItem value="npm" label="npm"> | ||
|
|
||
| ```sh | ||
| npm install | ||
| ``` | ||
|
|
||
| </TabItem> | ||
|
|
||
| <TabItem value="yarn" label="yarn"> | ||
|
|
||
| ```sh | ||
| yarn | ||
| ``` | ||
|
|
||
| </TabItem> | ||
|
|
||
| <TabItem value="pnpm" label="pnpm"> | ||
|
|
||
| ```sh | ||
| pnpm install | ||
| ``` | ||
|
|
||
| </TabItem> | ||
|
|
||
| </Tabs> | ||
|
|
||
| ### Bootstrapping the Packages | ||
|
|
||
| Refine uses [Lerna](https://lerna.js.org) to manage and run packages and examples. If you're unfamiliar with Lerna, you may get confused about how to run the packages in development mode but don't worry, we got you covered. By following the steps below, you will be able to prepare the packages and examples you're going to work on. | ||
|
|
||
| :::simple Development Tip | ||
|
|
||
| It's recommended to always keep at least one example ready to run while you are working on Refine. This way, you can test your changes in the example and make sure everything works as expected. | ||
|
|
||
| ::: | ||
|
|
||
| Let's start with bootstrapping a package and an example: | ||
|
|
||
| ```sh title="Terminal" | ||
| npm run bootstrap -- --scope @refinedev/antd --scope base-antd --includeDependencies | ||
| ``` | ||
|
|
||
| - We're using `--scope` flag to filter the packages and examples we want to bootstrap. In this example, we're bootstrapping `@refinedev/antd` package and `base-antd` example. | ||
| - `--includeDependencies` flag is used to tell Lerna to also include the dependencies of the packages and examples we've filtered to the bootstrapping process. | ||
|
|
||
| ### Building the Packages | ||
|
|
||
| After bootstrapping the packages we want to work on, we need to build them in order to run properly. You can use the command below to build the packages: | ||
|
|
||
| ```sh title="Terminal" | ||
| npm run build -- --scope @refinedev/antd --scope base-antd --includeDependencies | ||
| ``` | ||
|
|
||
| Just like the `bootstrap` command we're using `--scope` flag to filter the packages we want and use `--includeDependencies` flag to include the dependencies of the packages we've filtered. This way, we're including the dependencies of the packages we're working on to the build process. | ||
|
|
||
| ### Starting the Packages and Examples in Watch Mode | ||
|
|
||
| Now that we've bootstrapped and built the packages and examples we want to work on, we can start them in watch mode. This way, the packages and examples we've started will re-compile when we make a change in any of them. | ||
|
|
||
| ```sh title="Terminal" | ||
| npm run start -- --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. | ||
|
|
||
| :::simple Development Tip | ||
|
|
||
| Notice that we're not using `--includeDependencies` flag in this command. This is because we don't want to start the dependencies in watch mode. If we do, it will cause unnecessary re-compilations and slow down the development process. | ||
|
|
||
| ::: | ||
|
|
||
| ### Running Tests | ||
|
|
||
| Just like the `start` command, we can use the `test` command to run tests for the packages and examples we're working on. | ||
|
|
||
| ```sh title="Terminal" | ||
| npm run test -- --scope @refinedev/antd | ||
| ``` | ||
|
|
||
| :::simple Good to know | ||
|
|
||
| - Refine uses [Jest](https://jestjs.io/) as the test runner and [@testing-library/react](https://testing-library.com/docs/react-testing-library/intro/) for testing React components. For E2E tests, we're using [Cypress](https://www.cypress.io). | ||
| - We're expecting to see proper tests for each feature/bugfix you make. If you're not sure how to write tests for your feature/bugfix, please ask for help in our [community room](https://discord.gg/refine). | ||
|
|
||
| ::: | ||
|
|
||
| ## Working on Documentation | ||
|
|
||
| Refine documentation is built with [Docusaurus](https://docusaurus.io/). Documentation is handled separately from Lerna, so you need to install the dependencies and start the documentation separately. | ||
|
|
||
| ```sh title="Terminal" | ||
| cd documentation | ||
| npm install | ||
| npm run dev:docs | ||
| ``` | ||
|
|
||
| :::simple Documentation Scripts | ||
|
|
||
| - You can also use `npm run 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 `npm run start` command. | ||
|
|
||
| - To create a production build of the documentation, you can use `npm run build` command. Then, you can use `npm run serve` command to serve the production build in your local machine. | ||
|
|
||
| ::: | ||
|
|
||
| ### Creating Previews and Code Samples | ||
|
|
||
| We're using [Codesandbox's Sandpack](https://sandpack.codesandbox.io) 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: | ||
|
|
||
| - [useForm Documentation](https://refine.dev/docs/core/hooks/use-form/#usage) | ||
| - [Source Code for Sandpack](https://github.com/refinedev/refine/blob/master/documentation/docs/core/hooks/use-form/basic-usage.tsx) | ||
| - [Source Code for Markdown](https://github.com/refinedev/refine/blob/master/documentation/docs/core/hooks/use-form/index.md) | ||
|
|
||
| ## Committing Your Work and Preparing a Pull Request | ||
|
|
||
| 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. | ||
|
|
||
| ### Commit Convention | ||
|
|
||
| Commit messages are essential to keep everything clear in our development process. We use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) 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](https://commitlint.js.org/) 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. | ||
|
|
||
| ::: | ||
|
|
||
| ### Creating a Changeset | ||
|
|
||
| To manage our releases, changelogs and versioning, we're using [Changesets](https://github.com/changesets/changesets) and [Changesets GitHub Action](https://github.com/changesets/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: | ||
|
|
||
| ```sh | ||
| npm run changeset | ||
| ``` | ||
|
|
||
| After you run this command, you will be asked couple of questions: | ||
|
|
||
| - Select the package(s) you are modifying | ||
| - Choose one of `major/patch/minor` according to your change | ||
| - Add explanation about the changes | ||
|
|
||
| After 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 | ||
|
|
||
| - We're expecting a changeset to include a description about the changes you've made and how it affects the users. Please make sure you provide a good description for your changeset. | ||
| - It's required for a changeset to provide a link to the issue that is related with. If you don't have an issue for your changes, please create one and link it to your changeset. | ||
| - You'll be able to edit your changeset after you create it. If you need to make changes to your changeset, you can edit it under `.changeset` directory. | ||
|
|
||
| ::: | ||
|
|
||
| Check out the following examples to see how changesets should be formatted: | ||
|
|
||
| ```md title=".changeset/some-changeset.md" | ||
| --- | ||
| "@refinedev/core": minor | ||
| --- | ||
|
|
||
| feat: added x feature | ||
|
|
||
| Now with x feature, you can do y. | ||
|
|
||
| Resolves #1234 | ||
| ``` | ||
|
|
||
| or | ||
|
|
||
| ```md title=".changeset/some-other-changeset.md" | ||
| --- | ||
| "@refinedev/mantine": patch | ||
| --- | ||
|
|
||
| fix: issue with x. | ||
|
|
||
| We had an edge where it causes x issue to happen, now it's fixed. | ||
|
|
||
| Fixes #5678 | ||
| ``` | ||
|
|
||
| ### Creating a Pull Request | ||
|
|
||
| After you commit your changes and create a changeset, you can push your changes to your fork and [create a pull request](https://github.com/refinedev/refine/compare). 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! 🎉 | ||
|
|
||
| ## Release Cycle | ||
|
|
||
| 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 `master` 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. |
Oops, something went wrong.