From 18dae3c5f048746c7f39bceb8e8252e82d9901b1 Mon Sep 17 00:00:00 2001 From: Misite Bao Date: Tue, 23 Aug 2022 21:49:23 +0800 Subject: [PATCH] Reorganized contribution guidelines page (#1784) * feat(website): update dependencies * docs: reorganized contribution guidelines page * feat(website): modify the side directory configuration * chore: update issue documentation template and configuration --- .github/ISSUE_TEMPLATE/config.yml | 2 +- .github/ISSUE_TEMPLATE/documentation.yml | 2 +- website/docusaurus.config.js | 4 + website/package.json | 6 +- website/src/pages/community-guide.mdx | 172 +++++++++++++++++- .../contributing/developing-new-features.mdx | 30 --- .../src/pages/contributing/documenting.mdx | 42 ----- .../src/pages/contributing/fixing-bugs.mdx | 26 --- .../src/pages/contributing/helping-others.mdx | 13 -- .../setting-up-a-dev-environment.mdx | 29 --- website/src/pages/contributing/testing.mdx | 17 -- .../contributing/ways-of-contributing.mdx | 18 -- 12 files changed, 180 insertions(+), 181 deletions(-) delete mode 100644 website/src/pages/contributing/developing-new-features.mdx delete mode 100644 website/src/pages/contributing/documenting.mdx delete mode 100644 website/src/pages/contributing/fixing-bugs.mdx delete mode 100644 website/src/pages/contributing/helping-others.mdx delete mode 100644 website/src/pages/contributing/setting-up-a-dev-environment.mdx delete mode 100644 website/src/pages/contributing/testing.mdx delete mode 100644 website/src/pages/contributing/ways-of-contributing.mdx diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index f6ef439e8..7655d2651 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,4 +1,4 @@ -blank_issues_enabled: false +blank_issues_enabled: true contact_links: - name: GitHub Community Discussions url: https://github.com/wailsapp/wails/discussions diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml index 6efa67a20..5124ea777 100644 --- a/.github/ISSUE_TEMPLATE/documentation.yml +++ b/.github/ISSUE_TEMPLATE/documentation.yml @@ -20,7 +20,7 @@ body: attributes: label: Have you read the Documentation Contribution Guidelines? options: - - label: I have read the [Documentation Contribution Guidelines](https://wails.io/contributing/documenting). + - label: I have read the [Documentation Contribution Guidelines](https://wails.io/community-guide#ways-of-contributing). required: true - type: textarea diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 592aa6c97..37beb8f34 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -227,6 +227,10 @@ const config = { ], copyright: `Copyright © ${new Date().getFullYear()} Lea Anthony. Built with Docusaurus.`, }, + tableOfContents: { + minHeadingLevel: 2, + maxHeadingLevel: 5, + }, prism: { theme: lightCodeTheme, darkTheme: darkCodeTheme, diff --git a/website/package.json b/website/package.json index f7158f6cf..50b4b881b 100644 --- a/website/package.json +++ b/website/package.json @@ -14,9 +14,9 @@ "write-heading-ids": "docusaurus write-heading-ids" }, "dependencies": { - "@docusaurus/core": "2.0.0-beta.17", - "@docusaurus/preset-classic": "2.0.0-beta.17", - "@docusaurus/theme-search-algolia": "^2.0.0-beta.18", + "@docusaurus/core": "^2.0.1", + "@docusaurus/preset-classic": "^2.0.1", + "@docusaurus/theme-search-algolia": "^2.0.1", "@mdx-js/react": "^1.6.22", "@wails/react-contributors": "^1.1.3", "clsx": "^1.1.1", diff --git a/website/src/pages/community-guide.mdx b/website/src/pages/community-guide.mdx index b4cdc09de..35214b5e2 100644 --- a/website/src/pages/community-guide.mdx +++ b/website/src/pages/community-guide.mdx @@ -2,4 +2,174 @@ The number of Wails users is growing at an incredible rate, and if you're reading this, chances are you're ready to join. So... welcome! -To become a contributor please see the [ways of contributing](/contributing/ways-of-contributing). +## Resources + +### Code of Conduct + +coming soon... + +### Stay in the Know + +- Follow our [official Twitter account](https://twitter.com/wailsapp). + +### Get Support + +- [GitHub](https://github.com/wailsapp/wails) - If you have a bug to report or feature to request, that's what the GitHub issues are for. Please respect the rules specified in each repository's issue template. +- [Slack](https://gophers.slack.com/messages/CJ4P9F7MZ/) - A place for Wails devs to meet and chat in real time. +- [QQ Group(中文)](https://qm.qq.com/cgi-bin/qm/qr?k=PmIURne5hFGNd7QWzW5qd6FV-INEjNJv&jump_from=webapi) - A Wails group for Chinese developers to communicate, where you can get help from other developers. + +### Explore the Ecosystem + +- [The Awesome Wails Page](https://github.com/wailsapp/awesome-wails) - See what other awesome resources have been published by other awesome people. + +## Ways of contributing + +Wails is an open source, community driven project. We welcome anyone to join us in +contributing to the project. This documentation is aimed at anyone wishing to get +familiar with the project and the development processes. + +There are many ways to contribute to the project: + +- Developing new features +- Fixing bugs +- Testing +- Documenting features +- Writing tutorials / guides +- Helping others on the issues + discussions boards + +Guides for these have been created in their own sections. Before getting started, +please introduce yourself in the [Contributing to Wails](https://github.com/wailsapp/wails/discussions/1520) +discussion. + +### Developing New Features + +We are always keen to add features to Wails and expand on what the project can do. +The process for adding new features are as follows: + +- Pick an enhancement ticket with the "TODO" label. It's preferable to select one from the current + [Backlog](https://github.com/orgs/wailsapp/projects/1/views/1) but the choice is yours. +- Before developing, check that the ticket includes the following information: +- The purpose of the enhancement +- What is out of scope for the enhancement +- What platforms the enhancement targets (most features should be cross-platform unless there's a very specific reason) +- If the ticket does not include this information, feel free to request the information from the + person who opened the ticket. Sometimes placeholder tickets are created and require more details +- Comment on the ticket stating you wish to develop the feature +- Clone the repository and create a branch with the format `feature/_` +- New features often require documentation so please ensure you have also added or updated the documentation as part of + the changes +- Once the feature is ready for testing, create a draft PR. Please ensure the PR description has the test scenarios and + test cases listed with checkmarks, so that others can know what still needs to be tested. +- Once all the testing is completed, please update the status of the PR from draft and leave a message. + +:::note +There is nothing stopping you from opening a ticket and working on it yourself, but please be aware that all +enhancement requests are reviewed for good fit. Not all ideas will be selected so it's best to have discussion +on the ticket first. +::: + +:::warning +Any PRs opened without a corresponding ticket may be rejected. +::: + +### Fixing Bugs + +The process for fixing bugs are as follows: + +- Check the current [Backlog](https://github.com/orgs/wailsapp/projects/1/views/1) and select a bug to fix +- Before developing, check that the ticket includes the following information: +- The scope of the issue including platforms affected +- The steps to reproduce. Sometimes bugs are opened that are not Wails issues and the onus is on the reporter to + prove that it is a Wails issue with a minimal reproducible example +- The output of `wails doctor` +- If the ticket does not include this information, feel free to request the information from the + person who opened the ticket. +- Comment on the ticket stating you wish to develop a fix +- Clone the repository and create a branch with the format `bugfix/_` +- Once the fix is ready for testing, create a draft PR. Please ensure the PR description has the test scenarios and + test cases listed with checkmarks, so that others can know what still needs to be tested. +- Once all the testing is completed, please update the status of the PR from draft and leave a message. + +:::note +There is nothing stopping you from opening a ticket and working on it yourself, but please be aware that all +bugfixes should be discussed as the approach may have unintended side effects. +::: + +:::warning +Any PRs opened without a corresponding ticket may be rejected. +::: + +### Testing + +Testing is vitally important to ensure quality in the project. There are a couple of +scenarios where testing can really help the project: + +- Testing if a bug is reproducible on your local system +- Testing PRs to ensure that they work correctly + +If you chose to test if someone's bug report is reproducible on your local system, then +feel free to add a comment on the ticket confirming this with the output of `wails doctor`. + +To test PRs, choose a PR to test and check if the PR description has the testing scenarios +listed. If not, please ask the person who opened the PR to provide that list. Once you have +determined a valid test scenario, please report your findings on the PR. + +If you ever need more clarity or help on testing, please ask a question in the [Contributing to Wails](https://github.com/wailsapp/wails/discussions/1520) +discussion or on slack. + +### Documenting + +This website is also the main documentation site for the project. Sometimes this gets +out of date and needs some slight adjustments. Some of the documentation isn't written +to the best standards either. Developing documentation is hard and so any contribution +to this is greatly appreciated. Features without documentation are unfinished so to the +project, it's _as important_ as the code. + +We generally do not create tickets for updating documentation so if there is text you +think should be updated or rephrased then feel free to submit a PR for that. This site +is in the main repository under the `website` directory. We use [Docusaurus](https://docusaurus.io/) to create +the site so there is plenty of existing documentation and tutorials around to get started. + +To set up a local documentation development environment, do the following: + +- [Install npm](https://docs.npmjs.com/cli/v8/configuring-npm/install) +- `cd website` +- `npm install` +- `npm run start` + +After it has all installed and is running, you should see the site at [`http://localhost:3000`](http://localhost:3000). +Any changes made to the site text will be immediately reflected in the browser. + +#### Versioning + +We employ a versioning system where we have the "latest" documentation AKA "Next Version" which +has all the changes that have occurred since the last release. We also keep the last release +documentation as well as the version before that. + +There isn't usually a reason to update released documentation so we don't generally update +the documents in the `versioned_docs` or `versioned_sidebars` directories. + +The "next version" docs are mainly in `website/docs` with some "version independent" documents +in `src/pages`. Any updates should be made in the `website/docs` directory. + +#### Languages + +The default documents of the Wails project are English documents. We use the "crowdin" tool to translate documents in other languages and synchronize them to the website. You can [join our project](https://crowdin.com/project/wails) and submit your translations to make contributions. + +##### Add new language + +If you want to add a new language to the documentation, please follow the prompts to [fill in and submit an Issue](https://github.com/wailsapp/wails/issues/new?assignees=&labels=documentation&template=documentation.yml). After being confirmed by the maintainer, we will add the language to the "crowdin" and you will then be able to submit your translation. + +### Helping Others + +A great way to contribute to the project is to help others who are experiencing difficulty. +This is normally reported as a ticket or a message on the Wails slack channel. Even just +clarifying the issue can really help out. Sometimes, when an issue is discussed and gets +resolved, we create a guide out of it to help others who face the same issues. + +To join the Wails slack channel, accept the invite [here](https://gophers.slack.com/join/shared_invite/zt-197vymgt3-sJt4oyakb6nqlVKjXTyeVw#/shared-invite/email) +and join us on the channel by following [this link](https://gophers.slack.com/?redir=%2Fmessages%2FCJ4P9F7MZ%2F). + +:::note +Work In Progress +::: diff --git a/website/src/pages/contributing/developing-new-features.mdx b/website/src/pages/contributing/developing-new-features.mdx deleted file mode 100644 index 03bd7db6c..000000000 --- a/website/src/pages/contributing/developing-new-features.mdx +++ /dev/null @@ -1,30 +0,0 @@ -# Developing New Features - -We are always keen to add features to Wails and expand on what the project can do. -The process for adding new features are as follows: - -- Pick an enhancement ticket with the "TODO" label. It's preferable to select one from the current - [Backlog](https://github.com/orgs/wailsapp/projects/1/views/1) but the choice is yours. -- Before developing, check that the ticket includes the following information: -- The purpose of the enhancement -- What is out of scope for the enhancement -- What platforms the enhancement targets (most features should be cross-platform unless there's a very specific reason) -- If the ticket does not include this information, feel free to request the information from the - person who opened the ticket. Sometimes placeholder tickets are created and require more details -- Comment on the ticket stating you wish to develop the feature -- Clone the repository and create a branch with the format `feature/_` -- New features often require documentation so please ensure you have also added or updated the documentation as part of - the changes -- Once the feature is ready for testing, create a draft PR. Please ensure the PR description has the test scenarios and - test cases listed with checkmarks, so that others can know what still needs to be tested. -- Once all the testing is completed, please update the status of the PR from draft and leave a message. - -:::note -There is nothing stopping you from opening a ticket and working on it yourself, but please be aware that all -enhancement requests are reviewed for good fit. Not all ideas will be selected so it's best to have discussion -on the ticket first. -::: - -:::warning -Any PRs opened without a corresponding ticket may be rejected. -::: diff --git a/website/src/pages/contributing/documenting.mdx b/website/src/pages/contributing/documenting.mdx deleted file mode 100644 index d57d6d2a8..000000000 --- a/website/src/pages/contributing/documenting.mdx +++ /dev/null @@ -1,42 +0,0 @@ -# Documenting - -This website is also the main documentation site for the project. Sometimes this gets -out of date and needs some slight adjustments. Some of the documentation isn't written -to the best standards either. Developing documentation is hard and so any contribution -to this is greatly appreciated. Features without documentation are unfinished so to the -project, it's _as important_ as the code. - -We generally do not create tickets for updating documentation so if there is text you -think should be updated or rephrased then feel free to submit a PR for that. This site -is in the main repository under the `website` directory. We use [Docusaurus](https://docusaurus.io/) to create -the site so there is plenty of existing documentation and tutorials around to get started. - -To set up a local documentation development environment, do the following: - -- [Install npm](https://docs.npmjs.com/cli/v8/configuring-npm/install) -- `cd website` -- `npm install` -- `npm run start` - -After it has all installed and is running, you should see the site at [`http://localhost:3000`](http://localhost:3000). -Any changes made to the site text will be immediately reflected in the browser. - -## Versioning - -We employ a versioning system where we have the "latest" documentation AKA "Next Version" which -has all the changes that have occurred since the last release. We also keep the last release -documentation as well as the version before that. - -There isn't usually a reason to update released documentation so we don't generally update -the documents in the `versioned_docs` or `versioned_sidebars` directories. - -The "next version" docs are mainly in `website/docs` with some "version independent" documents -in `src/pages`. Any updates should be made in the `website/docs` directory. - -## Languages - -The default documents of the Wails project are English documents. We use the "crowdin" tool to translate documents in other languages and synchronize them to the website. You can [join our project](https://crowdin.com/project/wails) and submit your translations to make contributions. - -### Add new language - -If you want to add a new language to the documentation, please follow the prompts to [fill in and submit an Issue](https://github.com/wailsapp/wails/issues/new?assignees=&labels=documentation&template=documentation.yml). After being confirmed by the maintainer, we will add the language to the "crowdin" and you will then be able to submit your translation. diff --git a/website/src/pages/contributing/fixing-bugs.mdx b/website/src/pages/contributing/fixing-bugs.mdx deleted file mode 100644 index 0b23bf1d7..000000000 --- a/website/src/pages/contributing/fixing-bugs.mdx +++ /dev/null @@ -1,26 +0,0 @@ -# Fixing Bugs - -The process for fixing bugs are as follows: - -- Check the current [Backlog](https://github.com/orgs/wailsapp/projects/1/views/1) and select a bug to fix -- Before developing, check that the ticket includes the following information: -- The scope of the issue including platforms affected -- The steps to reproduce. Sometimes bugs are opened that are not Wails issues and the onus is on the reporter to - prove that it is a Wails issue with a minimal reproducible example -- The output of `wails doctor` -- If the ticket does not include this information, feel free to request the information from the - person who opened the ticket. -- Comment on the ticket stating you wish to develop a fix -- Clone the repository and create a branch with the format `bugfix/_` -- Once the fix is ready for testing, create a draft PR. Please ensure the PR description has the test scenarios and - test cases listed with checkmarks, so that others can know what still needs to be tested. -- Once all the testing is completed, please update the status of the PR from draft and leave a message. - -:::note -There is nothing stopping you from opening a ticket and working on it yourself, but please be aware that all -bugfixes should be discussed as the approach may have unintended side effects. -::: - -:::warning -Any PRs opened without a corresponding ticket may be rejected. -::: diff --git a/website/src/pages/contributing/helping-others.mdx b/website/src/pages/contributing/helping-others.mdx deleted file mode 100644 index 5b375f1c7..000000000 --- a/website/src/pages/contributing/helping-others.mdx +++ /dev/null @@ -1,13 +0,0 @@ -# Helping Others - -A great way to contribute to the project is to help others who are experiencing difficulty. -This is normally reported as a ticket or a message on the Wails slack channel. Even just -clarifying the issue can really help out. Sometimes, when an issue is discussed and gets -resolved, we create a guide out of it to help others who face the same issues. - -To join the Wails slack channel, accept the invite [here](https://gophers.slack.com/join/shared_invite/zt-197vymgt3-sJt4oyakb6nqlVKjXTyeVw#/shared-invite/email) -and join us on the channel by following [this link](https://gophers.slack.com/?redir=%2Fmessages%2FCJ4P9F7MZ%2F). - -:::note -Work In Progress -::: diff --git a/website/src/pages/contributing/setting-up-a-dev-environment.mdx b/website/src/pages/contributing/setting-up-a-dev-environment.mdx deleted file mode 100644 index 8663f4b7d..000000000 --- a/website/src/pages/contributing/setting-up-a-dev-environment.mdx +++ /dev/null @@ -1,29 +0,0 @@ -# Setting up a Development Environment - -You can set up a development environment by doing the following: - -- Install the latest versions of Go and Git -- `git clone https://github.com/wailsapp/wails` -- `cd wails/v2/cmd/wails` -- `go install` - -NOTE: The directory that you cloned the project into will now be called "clonedir". - -The Wails CLI will now be at the very latest version. - -To update projects to use the latest version, update the project's `go.mod` and -ensure the following line is at the bottom of the file: - -`replace github.com/wailsapp/wails/v2 => ` - -Example: - -On Windows: -`replace github.com/wailsapp/wails/v2 => C:\Users\leaan\Documents\wails-v2-beta\wails\v2` - -On 'nix: -`replace github.com/wailsapp/wails/v2 => /home/me/projects/wails/v2` - -To revert back to a stable version, run: - -`go install github.com/wailsapp/wails/v2/cmd/wails@latest` diff --git a/website/src/pages/contributing/testing.mdx b/website/src/pages/contributing/testing.mdx deleted file mode 100644 index 5d1567154..000000000 --- a/website/src/pages/contributing/testing.mdx +++ /dev/null @@ -1,17 +0,0 @@ -# Testing - -Testing is vitally important to ensure quality in the project. There are a couple of -scenarios where testing can really help the project: - -- Testing if a bug is reproducible on your local system -- Testing PRs to ensure that they work correctly - -If you chose to test if someone's bug report is reproducible on your local system, then -feel free to add a comment on the ticket confirming this with the output of `wails doctor`. - -To test PRs, choose a PR to test and check if the PR description has the testing scenarios -listed. If not, please ask the person who opened the PR to provide that list. Once you have -determined a valid test scenario, please report your findings on the PR. - -If you ever need more clarity or help on testing, please ask a question in the [Contributing to Wails](https://github.com/wailsapp/wails/discussions/1520) -discussion or on slack. diff --git a/website/src/pages/contributing/ways-of-contributing.mdx b/website/src/pages/contributing/ways-of-contributing.mdx deleted file mode 100644 index c66d426ce..000000000 --- a/website/src/pages/contributing/ways-of-contributing.mdx +++ /dev/null @@ -1,18 +0,0 @@ -# Ways of contributing - -Wails is an open source, community driven project. We welcome anyone to join us in -contributing to the project. This documentation is aimed at anyone wishing to get -familiar with the project and the development processes. - -There are many ways to contribute to the project: - -- Developing new features -- Fixing bugs -- Testing -- Documenting features -- Writing tutorials / guides -- Helping others on the issues + discussions boards - -Guides for these have been created in their own sections. Before getting started, -please introduce yourself in the [Contributing to Wails](https://github.com/wailsapp/wails/discussions/1520) -discussion.