From 91d6c23c713d3097cf606308e3e3afdea880de95 Mon Sep 17 00:00:00 2001 From: Lea Anthony Date: Sun, 3 Jul 2022 15:37:21 +1000 Subject: [PATCH] Updated contribution guide --- .../contributing/developing_new_features.mdx | 3 +- website/docs/contributing/documenting.mdx | 37 ++++++++++++++++-- website/docs/contributing/fixing_bugs.mdx | 2 +- website/docs/contributing/helping_others.mdx | 9 ++++- .../setting_up_a_dev_environment.mdx | 34 ++++++++++++++++ website/docs/contributing/testing.mdx | 21 ++++++++++ website/docs/guides/developing-wails.mdx | 39 ------------------- 7 files changed, 99 insertions(+), 46 deletions(-) create mode 100644 website/docs/contributing/setting_up_a_dev_environment.mdx create mode 100644 website/docs/contributing/testing.mdx delete mode 100644 website/docs/guides/developing-wails.mdx diff --git a/website/docs/contributing/developing_new_features.mdx b/website/docs/contributing/developing_new_features.mdx index 9f49bf45..1aa5ea14 100644 --- a/website/docs/contributing/developing_new_features.mdx +++ b/website/docs/contributing/developing_new_features.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 20 --- # Developing New Features @@ -32,3 +32,4 @@ on the ticket first. :::warning Any PRs opened without a corresponding ticket may be rejected. ::: + diff --git a/website/docs/contributing/documenting.mdx b/website/docs/contributing/documenting.mdx index 9a8c9342..1655a44f 100644 --- a/website/docs/contributing/documenting.mdx +++ b/website/docs/contributing/documenting.mdx @@ -1,10 +1,39 @@ --- -sidebar_position: 4 +sidebar_position: 40 --- # 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. -:::note -Work In Progress -::: diff --git a/website/docs/contributing/fixing_bugs.mdx b/website/docs/contributing/fixing_bugs.mdx index 8f7c60d1..7e1c78ad 100644 --- a/website/docs/contributing/fixing_bugs.mdx +++ b/website/docs/contributing/fixing_bugs.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 30 --- # Fixing Bugs diff --git a/website/docs/contributing/helping_others.mdx b/website/docs/contributing/helping_others.mdx index 86232c61..340f51a2 100644 --- a/website/docs/contributing/helping_others.mdx +++ b/website/docs/contributing/helping_others.mdx @@ -1,9 +1,16 @@ --- -sidebar_position: 5 +sidebar_position: 50 --- # 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/docs/contributing/setting_up_a_dev_environment.mdx b/website/docs/contributing/setting_up_a_dev_environment.mdx new file mode 100644 index 00000000..b5cfd8ec --- /dev/null +++ b/website/docs/contributing/setting_up_a_dev_environment.mdx @@ -0,0 +1,34 @@ +--- +sidebar_position: 10 +--- + +# 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/docs/contributing/testing.mdx b/website/docs/contributing/testing.mdx new file mode 100644 index 00000000..d0120465 --- /dev/null +++ b/website/docs/contributing/testing.mdx @@ -0,0 +1,21 @@ +--- +sidebar_position: 35 +--- + +# 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/docs/guides/developing-wails.mdx b/website/docs/guides/developing-wails.mdx deleted file mode 100644 index 58f9e9bd..00000000 --- a/website/docs/guides/developing-wails.mdx +++ /dev/null @@ -1,39 +0,0 @@ - -# Contributing - -This page is a guide on how to contribute to the Wails project. - -First, a word of warning: Wails v2 has been through a number of iterations and pivots. There is a lot of code that -is either on hold or deprecated. Reading the whole project and trying to understand it may be confusing. This document -aims to focus on what is current and how to understand that. - -## Bugs - -For raising bugs, please open a ticket on GitHub and give it the \[v2\] label. Include the output of `wails doctor` -in the ticket to help us understand your environment. - -For fixing bugs, please comment on a ticket that you'd like to take it on and we will put a label on the ticket. -It is best to use Windows as it is done in pure Go, making debugging much easier. - -## Features - -To request a new feature, raise a ticket so that it may be discussed. The ticket should be given the -"Feature Request" label. These will be discussed and if selected for development will be given the label -"Ready for Development". - -To implement a new feature, raise a ticket as above or select a ticket with the "Ready for Development" label. - -When raising a PR, be mindful to state what platforms the PR has been tested on. Any new feature will not be accepted unless it works -on all platforms (if it can). - -:::warning What not to do - -PRs for features with no tickets aren't helpful as there's no context to the PR and it will not be prioritised. - -::: - -## Documentation - -Contributing to the documentation is easy by clicking on the "Edit this page" link on any of the pages. Documentation -updates can be done ad-hoc, without a ticket. -