television/assets/js/e0ef48a2.1b5927d1.js

"use strict";(self.webpackChunktelevision_website=self.webpackChunktelevision_website||[]).push([[7592],{1934:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>c,contentTitle:()=>l,default:()=>d,frontMatter:()=>r,metadata:()=>i,toc:()=>a});const i=JSON.parse('{"id":"Developers/contributing","title":"Contributing","description":"First of all, thanks for considering contributing to this project. All contributions are welcome, whether they are bug reports, documentation improvements, feature requests, or pull requests.","source":"@site/../docs/02-Developers/00-contributing.md","sourceDirName":"02-Developers","slug":"/Developers/contributing","permalink":"/television/docs/Developers/contributing","draft":false,"unlisted":false,"tags":[],"version":"current","sidebarPosition":0,"frontMatter":{},"sidebar":"docSidebar","previous":{"title":"Showcase","permalink":"/television/docs/Users/showcase"},"next":{"title":"Architecture Documentation","permalink":"/television/docs/Developers/ARCHITECTURE"}}');var s=t(3420),o=t(5404);const r={},l="Contributing",c={},a=[{value:"Getting started",id:"getting-started",level:2},{value:"Prerequisites",id:"prerequisites",level:3},{value:"Forking the repository and setting up the project",id:"forking-the-repository-and-setting-up-the-project",level:3},{value:"Developing locally",id:"developing-locally",level:3},{value:"Contributing a new channel",id:"contributing-a-new-channel",level:3},{value:"Hot Topics",id:"hot-topics",level:2}];function h(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,o.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"contributing",children:"Contributing"})}),"\n",(0,s.jsx)(n.p,{children:"First of all, thanks for considering contributing to this project. All contributions are welcome, whether they are bug reports, documentation improvements, feature requests, or pull requests."}),"\n",(0,s.jsxs)(n.p,{children:["If you're not sure where to start, take a look at the ",(0,s.jsx)(n.a,{href:"#hot-topics",children:"Hot Topics"})," section for some ideas on what you could work on."]}),"\n",(0,s.jsx)(n.h1,{id:"contributing-to-televisions-documentation-website",children:"Contributing to television's documentation website"}),"\n",(0,s.jsxs)(n.p,{children:["To contribute to the docs, please refer to ",(0,s.jsx)(n.a,{href:"https://github.com/alexpasmantier/television/blob/main/website/CONTRIBUTING.md",children:"Contributing to docs"}),". This will guide you through the process of setting up the documentation environment and making changes."]}),"\n",(0,s.jsx)(n.h2,{id:"getting-started",children:"Getting started"}),"\n",(0,s.jsx)(n.h3,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,s.jsx)(n.p,{children:"These are pretty much the only things you need to have installed on your machine to get started with contributing to this project:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["the ",(0,s.jsx)(n.a,{href:"https://www.rust-lang.org/tools/install",children:"Rust"})," toolchain installed on your machine"]}),"\n",(0,s.jsxs)(n.li,{children:["any working version of ",(0,s.jsx)(n.a,{href:"https://git-scm.com/downloads",children:"Git"})]}),"\n",(0,s.jsxs)(n.li,{children:["the ",(0,s.jsx)(n.a,{href:"https://github.com/casey/just",children:"just"})," command runner"]}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"forking-the-repository-and-setting-up-the-project",children:"Forking the repository and setting up the project"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["Click on the ",(0,s.jsx)(n.code,{children:"Fork"})," button at the top right corner of the repository page to create a copy of the repository to your GitHub account."]}),"\n",(0,s.jsxs)(n.li,{children:["Clone the forked repository to your local machine by running the following command in your terminal:","\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"git clone https://github.com/<your-username>/television.git\n"})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["Navigate to the project directory and set up the upstream remote by running the following commands:","\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"cd television\ngit remote add upstream https://github.com/alexpasmantier/television.git\n"})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["Install the project dependencies by running the following command:","\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"just setup\n"})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["Create a new branch for your feature or bug fix:","\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"git checkout -b <branch-name>\n"})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["Make your changes and test them locally. Predefined commands are available to make your life simpler, using them spares some time and effort:","\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"just --list\n"})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["Once you're all set, commit them to your branch:","\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:'git add .\ngit commit -m "Your commit message"\n'})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["Push your changes to your forked repository:","\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"git push origin <branch-name>\n"})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["If not done automatically, create a pull request by navigating to the original repository and clicking on the ",(0,s.jsx)(n.code,{children:"New pull request"})," button."]}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:"developing-locally",children:"Developing locally"}),"\n",(0,s.jsx)(n.p,{children:"Before anything else (if not done already):"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"just setup\n"})}),"\n",(0,s.jsx)(n.p,{children:"To run the application in debug mode while developing, with the ability to see logs and debug information:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"just run\n"})}),"\n",(0,s.jsx)(n.p,{children:(0,s.jsx)(n.strong,{children:"Accessing the Logs:"})}),"\n",(0,s.jsxs)(n.p,{children:["The logs are written to a file called ",(0,s.jsx)(n.code,{children:"television.log"})," in a directory that depends on your operating system / configuration:"]}),"\n",(0,s.jsxs)(n.table,{children:[(0,s.jsx)(n.thead,{children:(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.th,{children:"Platform"}),(0,s.jsx)(n.th,{children:"Location"})]})}),(0,s.jsxs)(n.tbody,{children:[(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:"Linux"}),(0,s.jsxs)(n.td,{children:[(0,s.jsx)(n.code,{children:"$XDG_DATA_HOME/television/television.log"})," or ",(0,s.jsx)(n.code,{children:"$HOME/.local/share/television/television.log"})]})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:"macOS"}),(0,s.jsxs)(n.td,{children:[(0,s.jsx)(n.code,{children:"$XDG_DATA_HOME/television/television.log"})," or ",(0,s.jsx)(n.code,{children:"$HOME/Library/Application\\ Support/television/television.log"})]})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:"Windows"}),(0,s.jsx)(n.td,{children:(0,s.jsx)(n.code,{children:"{FOLDERID_LocalAppData}\\television\\television.log"})})]})]})]}),"\n",(0,s.jsx)(n.p,{children:"To check for linting and formatting issues (and fix them automatically), run:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"just fix\n"})}),"\n",(0,s.jsx)(n.p,{children:"To get a sense of the real thing and test how your patch would behave in production, run:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"just b release\n\n# or `just br`\n# or `just build release`\n"})}),"\n",(0,s.jsx)(n.p,{children:"Running the tests can be done with:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-shell",children:"just test\n"})}),"\n",(0,s.jsx)(n.h3,{id:"contributing-a-new-channel",children:"Contributing a new channel"}),"\n",(0,s.jsx)(n.p,{children:"Contributing a new channel is pretty straightforward."}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["create a new branch, add and commit your new channel's TOML file under ",(0,s.jsx)(n.code,{children:"cable/unix"})," (or ",(0,s.jsx)(n.code,{children:"cable/windows"})," depending on your usecase)"]}),"\n",(0,s.jsxs)(n.li,{children:["[optional] add a screenshot of the channel in ",(0,s.jsx)(n.code,{children:"assets/channels/<os>/"})," (e.g. ",(0,s.jsx)(n.code,{children:"assets/channels/unix/my_channel.png"}),")."]}),"\n",(0,s.jsx)(n.li,{children:"push your commit and create a PR"}),"\n",(0,s.jsx)(n.li,{children:"the ci will automatically generate the documentation for your channel and pick up the screenshot if available."}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"hot-topics",children:"Hot Topics"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"shell integration (autocomplete, keybindings)"}),"\n",(0,s.jsx)(n.li,{children:"packaging for various linux package managers (dnf, ...)"}),"\n",(0,s.jsx)(n.li,{children:"sorting options"}),"\n",(0,s.jsx)(n.li,{children:"ansi parsing"}),"\n",(0,s.jsx)(n.li,{children:"contributing new channels"}),"\n",(0,s.jsx)(n.li,{children:"improving code documentation"}),"\n"]})]})}function d(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(h,{...e})}):h(e)}},5404:(e,n,t)=>{t.d(n,{R:()=>r,x:()=>l});var i=t(6672);const s={},o=i.createContext(s);function r(e){const n=i.useContext(o);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function l(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:r(e.components),i.createElement(o.Provider,{value:n},e.children)}}}]);