mirror of
https://github.com/element-plus/element-plus.git
synced 2026-03-13 07:51:17 +08:00
chore(project): add code of conduct and commit example (#5255)
This commit is contained in:
jeremywu
118
CONTRIBUTING.md
Normal file
118
CONTRIBUTING.md
Normal file
@@ -0,0 +1,118 @@
|
||||
# How To Contribute
|
||||
|
||||
## Opening issues
|
||||
|
||||
- Before opening issue please search for the keyword see whether the issue you encountered has been reported already. :pray:
|
||||
|
||||
- Issues should be opened via [Issue Template](https://elementui.github.io/issue-generator/#/en-US?repo=element-plus), fill in the form to provide
|
||||
sufficient information to reproduce the issue, so that our developers can help you verify and fix it
|
||||
|
||||
**Insufficient information issue WILL BE CLOSED directly because we cannot reproduce them**
|
||||
|
||||
- Issues that with feature request should to go to [RFCs](https://github.com/element-plus/rfcs/issues). This helps us managing the project.
|
||||
|
||||
Next section is for those who wants to help develop Element Plus.
|
||||
|
||||
## Pre-request
|
||||
|
||||
You should be having:
|
||||
|
||||
NodeJS >= 16
|
||||
|
||||
Git > v2.20
|
||||
|
||||
Some of our compiling code used syntax that introduced in NodeJS>16.0 so you will be need to install that in advance.
|
||||
|
||||
## Clone the repository
|
||||
|
||||
1. Click the fork button on the top right of this page.
|
||||
2. Download the project to your machine.
|
||||
3. Run commands below to bootstrap the this project.
|
||||
|
||||
```shell
|
||||
cd $THE_PROJECT_PATH_YOU_DOWNLOADED
|
||||
# If you haven't installed yet
|
||||
pnpm install
|
||||
```
|
||||
|
||||
## Verify Installation
|
||||
|
||||
Then you can following command to verify your installation.
|
||||
|
||||
```shell
|
||||
pnpm test
|
||||
pnpm run format
|
||||
```
|
||||
|
||||
## Getting Started developing
|
||||
|
||||
Ah, now you have installed the code correctly, you can choose:
|
||||
|
||||
### Modify and update the documentation site.
|
||||
|
||||
```shell
|
||||
# If you would like to modify the website source code of https://element-plus.org
|
||||
# It was made with [VitePress](https://vitepress.vuejs.org)
|
||||
pnpm run docs:gen-locale # This generates locale files for your local development
|
||||
pnpm run docs:dev
|
||||
```
|
||||
|
||||
### Making changes to the component instead of website
|
||||
|
||||
```shell
|
||||
# If you would like to run a local playground to test out your changes against
|
||||
# Some specific component
|
||||
touch play/scr/App.vue # Adding an entry for the play to run.
|
||||
pnpm run dev
|
||||
```
|
||||
|
||||
You can follow the [LOCAL DEVELOPMENT GUIDE](https://github.com/element-plus/element-plus/blob/dev/LOCAL_DEV.md) to do development more quickly.
|
||||
|
||||
### Compile the source code
|
||||
|
||||
If you would like to compile this project locally:
|
||||
|
||||
```shell
|
||||
# This one line code would start compiling the code which was published to https://npmjs.com
|
||||
pnpm build
|
||||
```
|
||||
|
||||
### Compile documentation website
|
||||
|
||||
If you would like to compile the website code locally:
|
||||
|
||||
```shell
|
||||
DOC_ENV=production yarn docs:build
|
||||
```
|
||||
|
||||
## Pulling request
|
||||
|
||||
After you done your coding section, please note:
|
||||
|
||||
1. Update the tests to cover all cases
|
||||
2. Update co-responding documentation if you are making changes against API
|
||||
3. Write a comprehensive commit message
|
||||
4. Push your local changes to your remote, and then pull request to the upstream.
|
||||
5. In the description section, you can add more information about your changes, to help the reviewers for better
|
||||
understanding the context here.
|
||||
|
||||
## Commit template
|
||||
|
||||
We prepared a commit message template for you to refer to, you can also follow the instruction of the CLI tool to generate
|
||||
commit message intuitively.
|
||||
|
||||
1. With command
|
||||
|
||||
```bash
|
||||
pnpm cz
|
||||
```
|
||||
|
||||
2. You can also write the commit message by hand, but make sure your
|
||||
commit message follows the rules.
|
||||
|
||||
We have a [commit template](https://github.com/element-plus/element-plus/blob/dev/commit-example.md)
|
||||
|
||||
NOTE:
|
||||
**PRs with unformatted commit message WILL NOT BE ACCEPTED**
|
||||
|
||||
That's all, thanks for your contribution! 🤩
|
||||
63
LOCAL_DEV.md
Normal file
63
LOCAL_DEV.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# Local Development
|
||||
|
||||
## Generate new component
|
||||
|
||||
With command
|
||||
|
||||
```bash
|
||||
$ pnpm gen component-name
|
||||
```
|
||||
|
||||
Note the `component-name` must be in `kebab-case`, combining words by replacing each space with a dash.
|
||||
|
||||
And component type must be added to `typings/global.d.ts`.
|
||||
|
||||
## Bootstrap project
|
||||
|
||||
With command
|
||||
|
||||
```bash
|
||||
$ pnpm i
|
||||
```
|
||||
|
||||
the project will install all dependencies
|
||||
|
||||
## Website preview
|
||||
|
||||
With command
|
||||
|
||||
```bash
|
||||
$ pnpm docs:gen-locale
|
||||
$ pnpm docs:dev
|
||||
```
|
||||
|
||||
the project will launch website for you to preview all existing component
|
||||
|
||||
## Local development
|
||||
|
||||
See [Local development guide](https://github.com/element-plus/element-plus/CONTRIBUTING.md)
|
||||
|
||||
1. With command
|
||||
|
||||
```shell
|
||||
$ pnpm dev
|
||||
```
|
||||
|
||||
will start the local development environment
|
||||
|
||||
2. Add your component into `play/src/App.vue`
|
||||
|
||||
> App.vue
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<ComponentYouAreDeveloping />
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
// make sure this component is registered in @element-plus/components
|
||||
import { ComponentYouAreDeveloping } from '@element-plus/components'
|
||||
</script>
|
||||
```
|
||||
|
||||
Modify `App.vue` file per your needs to get things work.
|
||||
109
README.md
109
README.md
@@ -21,8 +21,18 @@
|
||||
|
||||
This project is still under heavy development. Feel free to join us and make your first pull request.
|
||||
|
||||
## Getting Started
|
||||
|
||||
Alright, for you to get started if you are looking for making Element Plus better you should keep reading.
|
||||
For developers that uses Element Plus to develop your website you should go ahead visit [Getting Started](https://element-plus.org/)
|
||||
|
||||
- 中国大陆[加速镜像站点](https://element-plus.gitee.io/)
|
||||
|
||||
### Playground
|
||||
|
||||
You can also try Element Plus out with the components built-in playground
|
||||
(This thing is still under development, most of the functions are ready)
|
||||
|
||||
#### Try it with code sandbox
|
||||
|
||||
[](https://codesandbox.io/s/element-plus-demo-dxtcr)
|
||||
@@ -64,99 +74,34 @@ This project is still under heavy development. Feel free to join us and make you
|
||||
Element Plus is translated to multiple languages, you can click the badge to help up update the translation or apply to become
|
||||
a proofreader [](https://crowdin.com/project/element-plus)
|
||||
|
||||
## Documentation
|
||||
For now we are only showing English and Chinese for resource reasons, but we are looking forward to translate it into more languages, please go to the link
|
||||
above and leave a message if you want to help translating Element Plus into your desired language.
|
||||
|
||||
You can find for more details, API, and other docs on [https://element-plus.org](https://element-plus.org/)
|
||||
|
||||
国内[加速镜像站点](https://element-plus.gitee.io/)
|
||||
## Stay tuned :eyes:
|
||||
|
||||
Join our [Discord](https://discord.link/ElementPlus) to start communicating with everybody.
|
||||
|
||||
## Breaking change list
|
||||
|
||||
**Note:** we are now currently preparing for the stable release, the APIs should be stable right now, we are going to
|
||||
make a full list about how to get upgraded from [Element UI](https://element.eleme.io) to Element Plus. This breaking change list
|
||||
might be updated day by day.
|
||||
|
||||
You can find the breaking change list here: [Breaking Change List](https://github.com/element-plus/element-plus/issues/162).
|
||||
|
||||
## Bootstrap project
|
||||
## This thing is broken, I should help improve it!
|
||||
|
||||
With command
|
||||
Awesommmmmmee. Everything you need is down below. You can also refer to
|
||||
[CONTRIBUTING](https://github.com/element-plus/element-plus/blob/dev/CONTRIBUTING.md) and
|
||||
[Code of Conduct](https://github.com/element-plus/element-plus/blob/dev/CODE_OF_CONDUCT.md)
|
||||
where you'll find the same information listed below.
|
||||
|
||||
```bash
|
||||
$ pnpm i
|
||||
```
|
||||
## I would like to become a part of the development team!
|
||||
|
||||
the project will install all dependencies
|
||||
Welcome :star_struck:! We are looking for talented developers to join us and making Element Plus better! If you care to join the development team, please
|
||||
reach out to us, you are more than welcomed to join us! :heart:
|
||||
|
||||
## Website preview
|
||||
|
||||
With command
|
||||
|
||||
```bash
|
||||
$ pnpm docs:dev
|
||||
```
|
||||
|
||||
the project will launch website for you to preview all existing component
|
||||
|
||||
## Local development
|
||||
|
||||
1. With command
|
||||
|
||||
```shell
|
||||
$ pnpm dev
|
||||
```
|
||||
|
||||
will start the local development environment
|
||||
|
||||
2. Add your component into `play/src/App.vue`
|
||||
|
||||
> App.vue
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<ComponentYouAreDeveloping />
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
// make sure this component is registered in @element-plus/components
|
||||
import { ComponentYouAreDeveloping } from '@element-plus/components'
|
||||
</script>
|
||||
```
|
||||
|
||||
Modify `App.vue` file per your needs to get things work.
|
||||
|
||||
## Component migration process
|
||||
|
||||
1. Convert the item in https://github.com/element-plus/element-plus/projects/1 to an issue
|
||||
2. Assign yourself to the issue
|
||||
3. Author your component by generating new component command below
|
||||
4. Migrate tests and docs
|
||||
5. Open a new pull request, fill in the component issue link in 1
|
||||
|
||||
## Generate new component
|
||||
|
||||
With command
|
||||
|
||||
```bash
|
||||
$ pnpm gen component-name
|
||||
```
|
||||
|
||||
Note the `component-name` must be in `kebab-case`, combining words by replacing each space with a dash.
|
||||
|
||||
And component type must be added to `typings/global.d.ts`.
|
||||
|
||||
## Commit template
|
||||
|
||||
With command
|
||||
|
||||
```bash
|
||||
pnpm cz
|
||||
```
|
||||
|
||||
Example
|
||||
|
||||
```
|
||||
# [TYPE](SCOPE): [el-component-name] DESCRIPTION#[ISSUE]
|
||||
# example: feat(components): [el-button] add type for form usage #1234
|
||||
```
|
||||
We are now lacking of experts of `Testing`, `GitHub Actions`, `PM`, if you do feel like you can and willing to help us, please do reach out to us. :pray:
|
||||
|
||||
## Sponsors
|
||||
|
||||
@@ -177,7 +122,7 @@ And thank you to all our backers! 🙏
|
||||
<img src="https://contrib.rocks/image?repo=element-plus/element-plus" />
|
||||
</a>
|
||||
|
||||
## Licence
|
||||
## License
|
||||
|
||||
Element Plus is open source software licensed as
|
||||
[MIT](https://github.com/element-plus/element-plus/blob/master/LICENSE).
|
||||
|
||||
77
commit-example.md
Normal file
77
commit-example.md
Normal file
@@ -0,0 +1,77 @@
|
||||
# Why this chapter exists
|
||||
|
||||
A good commit message enables us:
|
||||
|
||||
1. To understand what the contributor is trying to do
|
||||
2. Automatically generates change log
|
||||
|
||||
## Rule for writing commit message
|
||||
|
||||
```md
|
||||
# (If applied, this commit will...) <subject> (Max 72 characters)
|
||||
|
||||
# |<---- Using a Maximum Of 72 Characters ---->|
|
||||
|
||||
# Explain why this change is being made
|
||||
|
||||
# |<---- Try To Limit Each Line to a Maximum Of 72 Characters ---->|
|
||||
|
||||
# Provide links or keys to any relevant tickets, articles or other resources
|
||||
|
||||
# Use issues and merge requests' full URLs instead of short references,
|
||||
|
||||
# as they are displayed as plain text outside of GitLab
|
||||
|
||||
# --- COMMIT END ---
|
||||
|
||||
# --------------------
|
||||
|
||||
# Remember to
|
||||
|
||||
# Capitalize the subject line
|
||||
|
||||
# Use the imperative mood in the subject line
|
||||
|
||||
# Do not end the subject line with a period
|
||||
|
||||
# Subject must contain at least 3 words
|
||||
|
||||
# Separate subject from body with a blank line
|
||||
|
||||
# Commits that change 30 or more lines across at least 3 files should
|
||||
|
||||
# describe these changes in the commit body
|
||||
|
||||
# Do not use Emojis
|
||||
|
||||
# Use the body to explain what and why vs. how
|
||||
|
||||
# Can use multiple lines with "-" for bullet points in body
|
||||
|
||||
# For more information: https://chris.beams.io/posts/git-commit/
|
||||
|
||||
# --------------------
|
||||
```
|
||||
|
||||
## Template for commit messages
|
||||
|
||||
Below is a template commit message for your reference.
|
||||
|
||||
```md
|
||||
feat(components): [el-button] I did something with button
|
||||
|
||||
Blank between subject and body is expected.(period is expected)
|
||||
Describes your change in one line or multi-line.
|
||||
Capitalize your first letter when starting a new line
|
||||
Please do not exceeds 72 characters per line, because that would be harder to comprehend.
|
||||
|
||||
- You can also add bullet list symbol for better layout
|
||||
```
|
||||
|
||||
For the subject header, the format is:
|
||||
|
||||
```md
|
||||
[type](scope): [messages]
|
||||
```
|
||||
|
||||
You can checkout the allowed values for **type** and **scope** in [commitlint.config.js](https://github.com/element-plus/element-plus/blob/c2ee36a7fc72b17742d43ecdff4e2912c416141d/commitlint.config.js#L57),
|
||||
Reference in New Issue
Block a user