From 85ccceecaba2c047f7412492c17e78e1b9dc093f Mon Sep 17 00:00:00 2001 From: jeremywu <15975785+JeremyWuuuuu@users.noreply.github.com> Date: Sun, 9 Jan 2022 20:26:56 +0800 Subject: [PATCH] chore(project): add code of conduct and commit example (#5255) --- CONTRIBUTING.md | 118 ++++++++++++++++++++++++++++++++++++++++++++++ LOCAL_DEV.md | 63 +++++++++++++++++++++++++ README.md | 109 +++++++++++------------------------------- commit-example.md | 77 ++++++++++++++++++++++++++++++ 4 files changed, 285 insertions(+), 82 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 LOCAL_DEV.md create mode 100644 commit-example.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..d292987627 --- /dev/null +++ b/CONTRIBUTING.md @@ -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! 🀩 diff --git a/LOCAL_DEV.md b/LOCAL_DEV.md new file mode 100644 index 0000000000..83b90dd1da --- /dev/null +++ b/LOCAL_DEV.md @@ -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 + + + +``` + +Modify `App.vue` file per your needs to get things work. diff --git a/README.md b/README.md index aa6292768d..4315c035dd 100644 --- a/README.md +++ b/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 [![Edit element-plus](https://codesandbox.io/static/img/play-codesandbox.svg)](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 [![Crowdin](https://badges.crowdin.net/element-plus/localized.svg)](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 - - - -``` - -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! πŸ™ -## Licence +## License Element Plus is open source software licensed as [MIT](https://github.com/element-plus/element-plus/blob/master/LICENSE). diff --git a/commit-example.md b/commit-example.md new file mode 100644 index 0000000000..2acbdc855a --- /dev/null +++ b/commit-example.md @@ -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...) (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),