Skip to content

Commit

Permalink
docs: revamp contributing md
Browse files Browse the repository at this point in the history
  • Loading branch information
Esthefanie Vila Maior committed Aug 1, 2024
1 parent a0fb25f commit 73e15d8
Showing 1 changed file with 146 additions and 93 deletions.
239 changes: 146 additions & 93 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,38 +1,124 @@
# Contributing
# Contributing Guide for Yoga Design System

First of all, make sure you have all settings up for Yoga to run it locally:
This guide is to help developers contribute to the Yoga Design System efficiently. Our goal is to maintain smooth and organized collaboration, ensuring that all contributions are welcomed and properly integrated into the project.

1. Fork and clone this repo
2. Install dependencies using:
Wellhub developers should also consult the Internal Guidelines.

## Code of Conduct

We adopted the [Contributor Covenant](https://www.contributor-covenant.org/), which is widely used in many projects and communities such Node.js and React. Please read the [full text](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) so that you can understand what actions will and will not be tolerated.

## General Principles

- **Communication:** Check if there is already an [issue](https://github.com/gympass/yoga/issues) open in our repository. If not, you can create a new one, [like this example](https://github.com/gympass/yoga/issues/785). Also, check the [discussion topics](https://github.com/gympass/yoga/discussions). Our team will analyze and prioritize within our initiatives. If you are interested and available, let us know and we will address you ASAP.

- **Transparency:** All discussions about development and contributions should be conducted transparently so that all collaborators can follow the progress and provide feedback.

- **Documentation:** Documentation is crucial. Document all changes made and add clear comments to the code.

- **Quality:** We prioritize the quality of code and implementations. Make sure to follow our coding standards and perform comprehensive tests.

## Setup for Web Development

#### Fork and Clone

First of all, fork and clone this repository.

```bash
$ git clone [email protected]:gympass/yoga.git
```

### [NVM](https://github.com/nvm-sh/nvm)

NVM is a version manager for NodeJS, designed to be installed per-user, and invoked per-shell.

```bash
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
```

### [Node.js®](https://nodejs.org/en)

Node.js® is a free, open-source, cross-platform JavaScript runtime environment that lets developers create servers, web apps, command line tools and scripts. Attention: Make sure you are using node version 16.

```bash
$ nvm install 16
$ nvm use 16
$ node -v
```

#### [Yarn](https://yarnpkg.com/getting-started)

Yarn is an established open-source package manager used to manage dependencies in JavaScript projects. Start by enabling Corepack, if it isn't already.

```bash
$ corepack enable
```

Any time you'll want to update Yarn to the latest version, just run:

```bash
$ yarn
```

This project follows the
[conventional-commit](https://www.conventionalcommits.org/en/v1.0.0/) pattern
and, to help you with it, we use
[commitizen](http://commitizen.github.io/cz-cli/). So, everytime you want to
commit some change, please use:
### Build

We use our doc environment to build the components. The documentation app will open in your browser after a few seconds.

```bash
$ yarn dev:web
```
$ yarn commit

## Setup for Native Development

You should check [the official documentation](https://reactnative.dev/docs/set-up-your-environment) for installation instructions. In this guide, you'll learn how to set up your environment to run projects with Android Studio or Xcode and develop with Android emulators and iOS simulators.

Yoga has an app for iOS and Android, named LabNative, which is used to develop the native version of our components.

### Build iOS

For the iOS development, type, and the simulator will open automagically.

```bash
$ yarn dev:native:ios
```

We usually follow the `{{feat|fix|doc|ci}}/{{what-am-i-doing}}` for branch names.
### Build Android

First, you'll need to open a virtual device manually and then:

```bash
$ yarn dev:native:android
```

## New Component
### [React Native Doctor](https://www.npmjs.com/package/@react-native-community/cli-doctor)

At Yoga, a Component isn't just one file. It has its own docs, tests, exports,
native, web, and so on. To make it easy, there is a script at the root:
It is part of the React Native CLI. It contains commands for diagnosing and fixing common Node.js, iOS, Android & React Native issues.

```bash
$ npx react-native doctor
```

## Development Process

### 1. Branch Pattern

If you have been assigned a collaboration task, we will inform you about the branch created in the relevant issue or discussion topic.

### 2. Development

- **New doc:** If you want to add a documentation that isn't of a component, like this one, you can create an .md file under ./docs/content/guidelines and it will be automagically added.

- **New icon:** Just add the .svg file under packages/icons/src/svg and modify the flags.ts or ui.ts to reflect your changes. Remember to test with the fill property and without fill, see this PR as an example. In some error cases, try exporting and importing the icon again, or removing the mask or rect.

- **New Component:** At Yoga, a Component isn't just one file. It has its own docs, tests, exports, native, web, and so on. To make it easy, there is a script at the root.

```bash
$ yarn new NewComponent
```

This will create/edit all files for the NewComponent in web and native versions:

```
```bash
packages
├─doc
│ └─content
Expand All @@ -44,127 +130,94 @@ packages
│ └─newcomponent-web.mdx
├─labnative
│ └─pages
│ ├─index.js
│ └─NewComponent.jsx
│ ├─index.ts
│ └─NewComponent.tsx
└─yoga
└─src
├─NewComponent
│ ├─native
│ │ ├─index.js
│ │ ├─NewComponent.jsx
│ │ └─NewComponent.test.jsx
│ │ ├─index.ts
│ │ ├─NewComponent.tsx
│ │ └─NewComponent.test.tsx
│ ├─web
│ │ ├─index.js
│ │ ├─NewComponent.jsx
│ │ └─NewComponent.test.jsx
│ ├─NewComponent.theme.js
│ ├─index.js
│ └─index.native.js
├─index.js
└─index.native.js
│ │ ├─index.ts
│ │ ├─NewComponent.tsx
│ │ └─NewComponent.test.tsx
│ ├─NewComponent.theme.ts
│ ├─index.ts
│ └─index.native.ts
├─index.ts
└─index.native.ts
```

If you want to create a new component for only web or native version, you can add the respective flag:

```
```bash
$ yarn new NewComponent --web
```

```
or

```bash
$ yarn new NewComponent --native
```

### Theming

Every component has its own `theme` file. You can find it in its own folder.

When building a new component, make sure to add values like paddings, colors,
margins, to the component theme file.
- **New Theming:** Every component has its own `theme` file. You can find it in its own folder. When building a new component, make sure to add values like paddings, colors, margins, to the component theme file.

To create custom themes, Yoga exposes a `createTheme` function in order to generate new themes, you can refer to [Theme Generator](https://gympass.github.io/yoga/components/theming/themeGenerator) in order to see how to create custom themes.

### Web

We use our doc environment to build our components. To develop your component,
you can just type.

```
$ yarn dev:web
```

and the documentation app will open in your browser after few seconds.

### Native

For native development, certify you have all requirements as listed
[here](https://reactnative.dev/docs/environment-setup).

Yoga has an app, for iOS and Android, named as LabNative used to develop the
native version of our components.

#### iOS (Mac only)
### 3. Testing

For the iOS development, type, and the simulator will open automagically.
Add tests to ensure that your changes work as expected. Make sure all existing tests still pass. Remember to test on the operating systems and browsers we support.

```bash
$ yarn test
```
$ yarn dev:native:ios
```

### Android

First, you'll need to open a virtual device manually and then:
or specifying the platform

```bash
$ yarn test:native
$ yarn test:web
```
$ yarn dev:native:android
```

#### Documentation

Each component has a specific documentation for each platform.
All Yoga components have tests. To execute it for just one component, you can run:

#### Test

All Yoga components have tests. To execute it for just one component, you
can run:

```
```bash
$ yarn test /path/to/your/component
```

Or you can run it by a platform:

```
```bash
$ yarn test:web /path/to/your/component
$ yarn test:native /path/to/your/component
```

When you finish the development of your component, don't forget to add its
tests!
### 4. Commits

Before pushing your changes, certify all tests are passing, running:
Make clear and descriptive commits. This project follows the conventional-commit pattern and, to help you with it, we use [commitizen](http://commitizen.github.io/cz-cli/). So, everytime you want to commit some change, please use:

```bash
$ yarn commit
```
$ yarn test

// or specifying the platform
$ yarn test:native
$ yarn test:web
```
Push your changes to your fork:

## New Doc
```bash
$ git push origin branch-name
```

If you want to add a documentation that isn't of a component, like
[this one](https://gympass.github.io/yoga/guidelines/tokens), you can
create an `.md` file under `./docs/content/guidelines` and it will be automagically added.
### 5. Pull Requests

## New Icon
Open a Pull Request (PR) in the Yoga repository. Describe what was done, why it was done, and any other relevant details in the PR, following the template. Please always indicate in the PR when a design review is needed, along with images and videos.

Just add the `.svg` file under `packages/icons/src/svg` and modify the
`index.js` and `index.native.js` to reflect your changes.
### 6. Code Review Process

## Git Hooks
- **Internal Review:** Every change will be reviewed by at least two internal engineering and one design team members before being merged.
- **Request changes or comments:** Feedback will be provided directly in the PR. Please respond to suggestions and make the necessary changes.
- **Approval:** Once approved, the PR will be merged into the main branch by a Yoga team member.

We have two hooks inside Yoga repo:
### 7. Release Process

1. `pre-commit`: run eslint on all repo
2. `pre-push`: run `yarn test`
The deployment and release process begins after a Pull Request is merged into the repository. The content of each release can be viewed [here](https://github.com/gympass/yoga/releases). The published package on NPM can be found [here](https://www.npmjs.com/package/@gympass/yoga). Additionally, a notification is sent through internal communication channels to inform the team.

0 comments on commit 73e15d8

Please sign in to comment.