diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md index 416053e6..d9589e90 100644 --- a/docs/docs/contributing.md +++ b/docs/docs/contributing.md @@ -8,6 +8,13 @@ sidebar_position: 10 Contributions to Task are very welcome, but we ask that you read this document before submitting a PR. +:::note + +This document applies to the core [Task][task] repository _and_ [Task for Visual +Studio Code][vscode-task]. + +::: + ## Before you start - **Check existing work** - Is there an existing PR? Are there issues discussing @@ -24,18 +31,19 @@ before submitting a PR. - **Go** - Task is written in [Go][go]. We always support the latest two major Go versions, so make sure your version is recent enough. - **Node.js** - [Node.js][nodejs] is used to host Task's documentation server - and is required if you want to run this server locally. + and is required if you want to run this server locally. It is also required if + you want to contribute to the Visual Studio Code extension. - **Yarn** - [Yarn][yarn] is the Node.js package manager used by Task. ## 2. Making changes -- **Code style** - Try to maintain the existing code style where possible and - ensure that code is formatted by - [`gofumpt`](https://github.com/mvdan/gofumpt). We use - [`golangci-lint`](https://golangci-lint.run/) in our CI to enforce a - consistent style and best-practice. You can use the `task lint` command to run - this locally and the `task lint:fix` command to automatically fix any issues - that are found. +- **Code style** - Try to maintain the existing code style where possible. Go + code should be formatted by [`gofumpt`][gofumpt] and linted using + [`golangci-lint`][golangci-lint]. Any Markdown or TypeScript files should be + formatted and linted by [Prettier][prettier]. This style is enforced by our CI + to ensure that we have a consistent style across the project. You can use the + `task lint` command to lint the code locally and the `task lint:fix` command + to automatically fix any issues that are found. - **Documentation** - Ensure that you add/update any relevant documentation. See the [updating documentation](#updating-documentation) section below. - **Tests** - Ensure that you add/update any relevant tests and that all tests @@ -48,12 +56,20 @@ To run Task with working changes, you can use `go run ./cmd/task`. To run a development build of task against a test Taskfile in `testdata`, you can use `go run ./cmd/task --dir ./testdata/ `. +To run Task for Visual Studio Code, you can open the project in VSCode and hit +F5 (or whatever you debug keybind is set to). This will open a new VSCode window +with the extension running. Debugging this way is recommended as it will allow +you to set breakpoints and step through the code. Otherwise, you can run +`task package` which will generate a `.vsix` file that can be used to manually +install the extension. + ### Updating documentation -Task uses [Docusaurus][docusaurus] to host a documentation server. This can be -setup and run locally by using `task docs` (requires `nodejs` & `yarn`). All -content is written in Markdown and is located in the `docs/docs` directory. All -Markdown documents should have an 80 character line wrap limit. +Task uses [Docusaurus][docusaurus] to host a documentation server. The code for +this is located in the core Task repository. This can be setup and run locally +by using `task docs` (requires `nodejs` & `yarn`). All content is written in +Markdown and is located in the `docs/docs` directory. All Markdown documents +should have an 80 character line wrap limit (enforced by Prettier). When making a change, consider whether a change to the [Usage Guide](./usage.md) is necessary. This document contains descriptions and examples of how to use @@ -69,30 +85,38 @@ the schema should match. ### Writing tests -Most of Task's test are held in the `task_test.go` file in the project root and -this is where you'll most likely want to add new ones too. Most of these tests -also have a subdirectory in the `testdata` directory where any Taskfiles/data -required to run the tests are stored. +A lot of Task's tests are held in the `task_test.go` file in the project root +and this is where you'll most likely want to add new ones too. Most of these +tests also have a subdirectory in the `testdata` directory where any +Taskfiles/data required to run the tests are stored. When making a changes, consider whether new tests are required. These tests should ensure that the functionality you are adding will continue to work in the future. Existing tests may also need updating if you have changed Task's behavior. +You may also consider adding unit tests for any new functions you have added. +The unit tests should follow the Go convention of being location in a file named +`*_test.go` in the same package as the code being tested. + ## 3. Committing your code Try to write meaningful commit messages and avoid having too many commits on the PR. Most PRs should likely have a single commit (although for bigger PRs it may be reasonable to split it in a few). Git squash and rebase is your friend! +If you're not sure how to format your commit message, check out [Conventional +Commits][conventional-commits]. This style is not enforced, but it is a good way +to make your commit messages more readable and consistent. + ## 4. Submitting a PR - **Describe your changes** - Ensure that you provide a comprehensive description of your changes. - **Issue/PR links** - Link any previous work such as related issues or PRs. Please describe how your changes differ to/extend this work. -- **Examples** - Add any examples that you think are useful to demonstrate the - effect of your changes. +- **Examples** - Add any examples or screenshots that you think are useful to + demonstrate the effect of your changes. - **Draft PRs** - If your changes are incomplete, but you would like to discuss them, open the PR as a draft and add a comment to start a discussion. Using comments rather than the PR description allows the description to be updated @@ -102,7 +126,8 @@ be reasonable to split it in a few). Git squash and rebase is your friend! > I want to contribute, where do I start? -Take a look at the list of [open issues][open-issues]. We have a [good first +Take a look at the list of [open issues for Task][task-open-issues] or [Task for +Visual Studio Code][vscode-task-open-issues]. We have a [good first issue][good-first-issue] label for simpler issues that are ideal for first time contributions. @@ -118,13 +143,20 @@ If you have questions, feel free to ask them in the `#help` forum channel on our --- +[task]: https://github.com/go-task/task +[vscode-task]: https://github.com/go-task/vscode-task [go]: https://go.dev +[gofumpt]: https://github.com/mvdan/gofumpt +[golangci-lint]: https://golangci-lint.run +[prettier]: https://prettier.io [nodejs]: https://nodejs.org/en/ [yarn]: https://yarnpkg.com/ [docusaurus]: https://docusaurus.io [json-schema]: https://github.com/go-task/task/blob/main/docs/static/schema.json -[open-issues]: https://github.com/go-task/task/issues +[task-open-issues]: https://github.com/go-task/task/issues +[vscode-task-open-issues]: https://github.com/go-task/vscode-task/issues [good-first-issue]: https://github.com/go-task/task/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22 [discord-server]: https://discord.gg/6TY36E39UK [discussion]: https://github.com/go-task/task/discussions +[conventional-commits]: https://www.conventionalcommits.org