go-task/assets/js/4d54d076.c115a808.js

"use strict";(self.webpackChunktaskfile_dev=self.webpackChunktaskfile_dev||[]).push([[80],{3905:function(e,t,n){n.d(t,{Zo:function(){return c},kt:function(){return h}});var a=n(7294);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,a)}return n}function r(e){for(var t=1;t<arguments.length;t++){var n=null!=arguments[t]?arguments[t]:{};t%2?i(Object(n),!0).forEach((function(t){o(e,t,n[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(n)):i(Object(n)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(n,t))}))}return e}function s(e,t){if(null==e)return{};var n,a,o=function(e,t){if(null==e)return{};var n,a,o={},i=Object.keys(e);for(a=0;a<i.length;a++)n=i[a],t.indexOf(n)>=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a<i.length;a++)n=i[a],t.indexOf(n)>=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var u=a.createContext({}),l=function(e){var t=a.useContext(u),n=t;return e&&(n="function"==typeof e?e(t):r(r({},t),e)),n},c=function(e){var t=l(e.components);return a.createElement(u.Provider,{value:t},e.children)},d="mdxType",p={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},m=a.forwardRef((function(e,t){var n=e.components,o=e.mdxType,i=e.originalType,u=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),d=l(n),m=o,h=d["".concat(u,".").concat(m)]||d[m]||p[m]||i;return n?a.createElement(h,r(r({ref:t},c),{},{components:n})):a.createElement(h,r({ref:t},c))}));function h(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=n.length,r=new Array(i);r[0]=m;var s={};for(var u in t)hasOwnProperty.call(t,u)&&(s[u]=t[u]);s.originalType=e,s[d]="string"==typeof e?e:o,r[1]=s;for(var l=2;l<i;l++)r[l]=n[l];return a.createElement.apply(null,r)}return a.createElement.apply(null,n)}m.displayName="MDXCreateElement"},1933:function(e,t,n){n.r(t),n.d(t,{assets:function(){return u},contentTitle:function(){return r},default:function(){return d},frontMatter:function(){return i},metadata:function(){return s},toc:function(){return l}});var a=n(3117),o=(n(7294),n(3905));const i={slug:"/contributing/",sidebar_position:11},r="Contributing",s={unversionedId:"contributing",id:"contributing",title:"Contributing",description:"Contributions to Task are very welcome, but we ask that you read this document",source:"@site/docs/contributing.md",sourceDirName:".",slug:"/contributing/",permalink:"/contributing/",draft:!1,tags:[],version:"current",sidebarPosition:11,frontMatter:{slug:"/contributing/",sidebar_position:11},sidebar:"tutorialSidebar",previous:{title:"Community",permalink:"/community/"},next:{title:"Translate",permalink:"/translate/"}},u={},l=[{value:"Before you start",id:"before-you-start",level:2},{value:"1. Setup",id:"1-setup",level:2},{value:"2. Making changes",id:"2-making-changes",level:2},{value:"Running your changes",id:"running-your-changes",level:3},{value:"Updating documentation",id:"updating-documentation",level:3},{value:"Writing tests",id:"writing-tests",level:3},{value:"3. Committing your code",id:"3-committing-your-code",level:2},{value:"4. Submitting a PR",id:"4-submitting-a-pr",level:2},{value:"FAQ",id:"faq",level:2}],c={toc:l};function d(e){let{components:t,...n}=e;return(0,o.kt)("wrapper",(0,a.Z)({},c,n,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("h1",{id:"contributing"},"Contributing"),(0,o.kt)("p",null,"Contributions to Task are very welcome, but we ask that you read this document\nbefore submitting a PR."),(0,o.kt)("admonition",{type:"note"},(0,o.kt)("p",{parentName:"admonition"},"This document applies to the core ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/go-task/task"},"Task")," repository ",(0,o.kt)("em",{parentName:"p"},"and")," ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/go-task/vscode-task"},"Task for Visual\nStudio Code"),".")),(0,o.kt)("h2",{id:"before-you-start"},"Before you start"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"Check existing work")," - Is there an existing PR? Are there issues discussing\nthe feature/change you want to make? Please make sure you consider/address\nthese discussions in your work."),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"Backwards compatibility")," - Will your change break existing Taskfiles? It is\nmuch more likely that your change will merged if it backwards compatible. Is\nthere an approach you can take that maintains this compatibility? If not,\nconsider opening an issue first so that API changes can be discussed before\nyou invest your time into a PR."),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"Experiments"),' - If there is no way to make your change backward compatible\nthen there is a procedure to introduce breaking changes into minor versions.\nWe call these "',"[experiments][experiments]","\". If you're intending to work on an\nexperiment, then please read the ","[experiments workflow][experiments-workflow]","\ndocument carefully and submit a proposal first.")),(0,o.kt)("h2",{id:"1-setup"},"1. Setup"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"Go")," - Task is written in ",(0,o.kt)("a",{parentName:"li",href:"https://go.dev"},"Go"),". We always support the latest two major\nGo versions, so make sure your version is recent enough."),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"Node.js")," - ",(0,o.kt)("a",{parentName:"li",href:"https://nodejs.org/en/"},"Node.js")," is used to host Task's documentation server\nand is required if you want to run this server locally. It is also required if\nyou want to contribute to the Visual Studio Code extension."),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"Yarn")," - ",(0,o.kt)("a",{parentName:"li",href:"https://yarnpkg.com/"},"Yarn")," is the Node.js package manager used by Task.")),(0,o.kt)("h2",{id:"2-making-changes"},"2. Making changes"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"Code style")," - Try to maintain the existing code style where possible. Go\ncode should be formatted by ",(0,o.kt)("a",{parentName:"li",href:"https://github.com/mvdan/gofumpt"},(0,o.kt)("inlineCode",{parentName:"a"},"gofumpt"))," and linted using\n",(0,o.kt)("a",{parentName:"li",href:"https://golangci-lint.run"},(0,o.kt)("inlineCode",{parentName:"a"},"golangci-lint")),". Any Markdown or TypeScript files should be\nformatted and linted by ",(0,o.kt)("a",{parentName:"li",href:"https://prettier.io"},"Prettier"),". This style is enforced by our CI\nto ensure that we have a consistent style across the project. You can use the\n",(0,o.kt)("inlineCode",{parentName:"li"},"task lint")," command to lint the code locally and the ",(0,o.kt)("inlineCode",{parentName:"li"},"task lint:fix")," command\nto automatically fix any issues that are found."),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"Documentation")," - Ensure that you add/update any relevant documentation. See\nthe ",(0,o.kt)("a",{parentName:"li",href:"#updating-documentation"},"updating documentation")," section below."),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"Tests")," - Ensure that you add/update any relevant tests and that all tests\nare passing before submitting the PR. See the ",(0,o.kt)("a",{parentName:"li",href:"#writing-tests"},"writing tests"),"\nsection below.")),(0,o.kt)("h3",{id:"running-your-changes"},"Running your changes"),(0,o.kt)("p",null,"To run Task with working changes, you can use ",(0,o.kt)("inlineCode",{parentName:"p"},"go run ./cmd/task"),". To run a\ndevelopment build of task against a test Taskfile in ",(0,o.kt)("inlineCode",{parentName:"p"},"testdata"),", you can use\n",(0,o.kt)("inlineCode",{parentName:"p"},"go run ./cmd/task --dir ./testdata/<my_test_dir> <task_name>"),"."),(0,o.kt)("p",null,"To run Task for Visual Studio Code, you can open the project in VSCode and hit\nF5 (or whatever you debug keybind is set to). This will open a new VSCode window\nwith the extension running. Debugging this way is recommended as it will allow\nyou to set breakpoints and step through the code. Otherwise, you can run\n",(0,o.kt)("inlineCode",{parentName:"p"},"task package")," which will generate a ",(0,o.kt)("inlineCode",{parentName:"p"},".vsix")," file that can be used to manually\ninstall the extension."),(0,o.kt)("h3",{id:"updating-documentation"},"Updating documentation"),(0,o.kt)("p",null,"Task uses ",(0,o.kt)("a",{parentName:"p",href:"https://docusaurus.io"},"Docusaurus")," to host a documentation server. The code for\nthis is located in the core Task repository. This can be setup and run locally\nby using ",(0,o.kt)("inlineCode",{parentName:"p"},"task docs")," (requires ",(0,o.kt)("inlineCode",{parentName:"p"},"nodejs")," & ",(0,o.kt)("inlineCode",{parentName:"p"},"yarn"),"). All content is written in\nMarkdown and is located in the ",(0,o.kt)("inlineCode",{parentName:"p"},"docs/docs")," directory. All Markdown documents\nshould have an 80 character line wrap limit (enforced by Prettier)."),(0,o.kt)("p",null,"When making a change, consider whether a change to the ",(0,o.kt)("a",{parentName:"p",href:"/usage/"},"Usage Guide"),"\nis necessary. This document contains descriptions and examples of how to use\nTask features. If you're adding a new feature, try to find an appropriate place\nto add a new section. If you're updating an existing feature, ensure that the\ndocumentation and any examples are up-to-date. Ensure that any examples follow\nthe ",(0,o.kt)("a",{parentName:"p",href:"/styleguide/"},"Taskfile Styleguide"),"."),(0,o.kt)("p",null,"If you added a new field, command or flag, ensure that you add it to the\n",(0,o.kt)("a",{parentName:"p",href:"/api/"},"API Reference"),". New fields also need to be added to the\n",(0,o.kt)("a",{parentName:"p",href:"https://github.com/go-task/task/blob/main/docs/static/schema.json"},"JSON Schema"),". The descriptions for fields in the API reference and\nthe schema should match."),(0,o.kt)("h3",{id:"writing-tests"},"Writing tests"),(0,o.kt)("p",null,"A lot of Task's tests are held in the ",(0,o.kt)("inlineCode",{parentName:"p"},"task_test.go")," file in the project root\nand this is where you'll most likely want to add new ones too. Most of these\ntests also have a subdirectory in the ",(0,o.kt)("inlineCode",{parentName:"p"},"testdata")," directory where any\nTaskfiles/data required to run the tests are stored."),(0,o.kt)("p",null,"When making a changes, consider whether new tests are required. These tests\nshould ensure that the functionality you are adding will continue to work in the\nfuture. Existing tests may also need updating if you have changed Task's\nbehavior."),(0,o.kt)("p",null,"You may also consider adding unit tests for any new functions you have added.\nThe unit tests should follow the Go convention of being location in a file named\n",(0,o.kt)("inlineCode",{parentName:"p"},"*_test.go")," in the same package as the code being tested."),(0,o.kt)("h2",{id:"3-committing-your-code"},"3. Committing your code"),(0,o.kt)("p",null,"Try to write meaningful commit messages and avoid having too many commits on the\nPR. Most PRs should likely have a single commit (although for bigger PRs it may\nbe reasonable to split it in a few). Git squash and rebase is your friend!"),(0,o.kt)("p",null,"If you're not sure how to format your commit message, check out ",(0,o.kt)("a",{parentName:"p",href:"https://www.conventionalcommits.org"},"Conventional\nCommits"),". This style is not enforced, but it is a good way\nto make your commit messages more readable and consistent."),(0,o.kt)("h2",{id:"4-submitting-a-pr"},"4. Submitting a PR"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"Describe your changes")," - Ensure that you provide a comprehensive\ndescription of your changes."),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"Issue/PR links")," - Link any previous work such as related issues or PRs.\nPlease describe how your changes differ to/extend this work."),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"Examples")," - Add any examples or screenshots that you think are useful to\ndemonstrate the effect of your changes."),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"Draft PRs")," - If your changes are incomplete, but you would like to discuss\nthem, open the PR as a draft and add a comment to start a discussion. Using\ncomments rather than the PR description allows the description to be updated\nlater while preserving any discussions.")),(0,o.kt)("h2",{id:"faq"},"FAQ"),(0,o.kt)("blockquote",null,(0,o.kt)("p",{parentName:"blockquote"},"I want to contribute, where do I start?")),(0,o.kt)("p",null,"Take a look at the list of ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/go-task/task/issues"},"open issues for Task")," or ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/go-task/vscode-task/issues"},"Task for\nVisual Studio Code"),". We have a ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/go-task/task/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22"},"good first\nissue")," label for simpler issues that are ideal for first time\ncontributions."),(0,o.kt)("p",null,"All kinds of contributions are welcome, whether its a typo fix or a shiny new\nfeature. You can also contribute by upvoting/commenting on issues, helping to\nanswer questions or contributing to other ",(0,o.kt)("a",{parentName:"p",href:"/community/"},"community projects"),"."),(0,o.kt)("blockquote",null,(0,o.kt)("p",{parentName:"blockquote"},"I'm stuck, where can I get help?")),(0,o.kt)("p",null,"If you have questions, feel free to ask them in the ",(0,o.kt)("inlineCode",{parentName:"p"},"#help")," forum channel on our\n",(0,o.kt)("a",{parentName:"p",href:"https://discord.gg/6TY36E39UK"},"Discord server")," or open a ",(0,o.kt)("a",{parentName:"p",href:"https://github.com/go-task/task/discussions"},"Discussion")," on GitHub."),(0,o.kt)("hr",null))}d.isMDXComponent=!0}}]);