From d88433b2d92516fd7cfd4c3b5fcc2b75e42a595d Mon Sep 17 00:00:00 2001 From: zkldi <20380519+zkldi@users.noreply.github.com> Date: Sat, 13 Aug 2022 01:21:55 +0100 Subject: [PATCH] feat: first contributing draft --- docs/docs/contributing.md | 95 ----- docs/docs/contributing/components.md | 101 +++++ .../contributing/components/documentation.md | 52 +++ docs/docs/contributing/components/issues.md | 31 ++ docs/docs/contributing/overview.md | 97 +---- docs/docs/contributing/setup.md | 197 ++++++++++ docs/docs/contributing/tools/terminal.md | 367 ++++++++++++++++++ docs/docs/index.md | 9 +- docs/docs/tachi-server/contributing.md | 34 -- docs/docs/tachi-server/setup/setup.md | 1 - docs/mkdocs.yml | 17 +- 11 files changed, 775 insertions(+), 226 deletions(-) delete mode 100644 docs/docs/contributing.md create mode 100644 docs/docs/contributing/components.md create mode 100644 docs/docs/contributing/components/documentation.md create mode 100644 docs/docs/contributing/components/issues.md create mode 100644 docs/docs/contributing/setup.md create mode 100644 docs/docs/contributing/tools/terminal.md delete mode 100644 docs/docs/tachi-server/contributing.md delete mode 100644 docs/docs/tachi-server/setup/setup.md diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md deleted file mode 100644 index eae155546..000000000 --- a/docs/docs/contributing.md +++ /dev/null @@ -1,95 +0,0 @@ -# Contributing to Tachi - -## For Newcomers - -If you're looking to contribute to Tachi but aren't -really familiar with TypeScript or other things -we use, Documentation Contributions are highly -appreciated, and accessible to do without any -programming knowledge. - -If you're not familiar with git, I would recommend -downloading [GitHub Desktop](https://desktop.github.com/). - -It has a nice, intuitive UI for making changes, and -saves the trouble of having to explain how forks work. - -## Documentation Contributions - -The documentation for Tachi may have typos, slight mistakes -or inconsistencies. Fixes for those are always appreciated. - -Larger documentation contributions (such as documenting -logic in the codebase) may be subject to some more scrutiny -to make sure that they are correct, but are also significantly appreciated. - -To contribute to the documentation, you should go to -the [GitHub](https://github.com/TNG-dev/Tachi), and -fork the repository. - -## Non-Code Contributions - -Inside the Discord Servers for Bokutachi and Kamaitachi is -a `#help-wanted` channel. This channel lists things that I -currently cannot do, either for time or knowledge reasons. - -These are not code related contributions, and can range from -cool images of cabinets/setups to milestones for a game. - -These are also significantly appreciated. - -## Code Contributions - -You should follow the code style of the project, and make issues before you make PRs! - -### Pull Requests - -You can contribute to `tachi` by forking -and then making your changes. - -There are a couple of strict guidelines to follow when -writing code contributions (Pull Requests). Not following these may -result in your pull request being rejected. - -- Write tests. - -Your new code should be tested if applicable. - -- Follow the style guide. - -Your new code should follow the style of the repo. The linter -should not have any errors. Generally, write code that -looks like it belongs. - -- Your PR should fix an issue. - -If there isn't an issue for your PR, you should make one -before making the PR. - -For larger PRs, such as making new features/new support, -you should make the issue in advance so discussion can -occur (so you don't waste your time on code that can't -be merged). - -### Issues - -Submitting issues to `tachi` is encouraged. Despite -the GitHub name of 'issues', issues may also be feature -requests, new support requests, and similar things. - -Guidelines for submitting issues are as follows: - -- Be Nice. - -Self-explanatory. Remember the human! - -- Make sure your issue isn't already reported as a duplicate. - -This saves me a lot of time. If there's a similar issue -but you think yours is different enough to warrant a new -issue, then that's fine. - -- If this is a bug report, be as specific as possible. - -Something like "It wont work" does not help at all. -Non-Specific bug reports will be closed immediately and marked as invalid. diff --git a/docs/docs/contributing/components.md b/docs/docs/contributing/components.md new file mode 100644 index 000000000..697b5f7fd --- /dev/null +++ b/docs/docs/contributing/components.md @@ -0,0 +1,101 @@ +# Contribution Guides + +The Tachi repository that you just set up is made up of multiple "components". + +All of them have their own things going on, so this page has all the guides for each specific component. + +## For Professionals... + +If you're already very familiar with `git`, the terminal, `node` and JSON, and care more about Tachi specific stuff (how to get the components running, what our architecture looks like), you should skip over that stuff in each guide. + +We maintain these guides so that people with knowledge about how to improve Tachi can help out, regardless of their skill level! As such, not all of the information will be of use to you - Skip over the easy bits. + +## What can I contribute to? + +In order of difficulty, here are the components of Tachi you can contribute to! + +All of these sections summarise a part of Tachi, and end with a link to a guide you can use to +contribute to it. + +### Issue Reports + +You can report issues on the [GitHub](https://github.com/TNG-Dev/Tachi) repository. This requires +*absolutely no programming knowledge* on your part. All you have to do is write up a nice summary +of the bug. + +!!! note + Although they're called GitHub *issues*, they're actually used for tracking anything. If you've + came up with a cool feature idea, send it over as an issue! `zkldi` will read and Triage them. + +For more information, read our [Issue Reporting Guide](./components/issues.md). + +### Documentation + +We store our documentation as a series of markdown files in the [Main Repository](https://github.com/TNG-Dev/Tachi). You can find it under the `docs/` folder. + +Writing, maintaining and proofreading the documentation is something that is **severely** neglected +at the moment. Simple things like typo fixes, all the way up to writing new explanations about major features +are **thoroughly** appreciated, as `zkldi` prioritises maintaining the core of working code. + +If you're interested in this, check out the [Documentation Contribution Guide](./docs.md). + +It'll teach you `shell` and `git` basics, +setting up a programming environment for Tachi, +and how to use our documentation builder. + +### Database Seeds + +We use an interesting system for parts of our database. We actually store a game's songs and charts *in* +our GitHub repository! That means you can: + +- Open the `songs` file for a game. +- Edit a `title` of a song that has a typo. +- Add a couple new songs that were added in the latest update +- Submit your changes back and if they're accepted... +- They automatically synchronise with the site! + +!!! important + This part of Tachi is the most important part for external contributors. + You guys know these games better than `zkldi` does, and you guys keep an eye on all the updates for your games! + + If people don't add songs/charts to this database, `zkldi` will **not** keep an eye on the game for you! Someone *has* to pick up the reigns for each game! + + If you want to add/fix songs, charts, folders or tables for your favourite game - **START HERE!** + + Or in general, if you just want to contribute and don't know what to -- **this is the MOST in need of help. Always.** + +Want to get started on contributing to the Database? Check out our [Database Contribution Guide](./database.md). + +It'll teach you `shell` and `git` basics, +setting up a programming environment for Tachi, +`json`, +and we'll even do a little scripting as a treat! + +### Server, Client + +The server and client form the powerful *core* of Tachi. + +The server handles all of our logic -- How do we get scores, where should scores come from, how do we calculate all these stats and way more. + +The client tries to then place a slick UI over that logic and its exposed API. + +!!! warning + Tachi's core is not an amazingly complex beast, but it is *not* going to be reasonably followable + with not a lot of programming experience. You'll need some background in programming to be able to do almost anything in this area. + + That said, we still have a thorough guide -- It's not *from 0*, but it is *from some programming knowledge*. + +Want to get started on contributing to the Core? Check out our [Core Contribution Guide](./core.md). + +We'll cover... + +- Running a local development instance of Tachi. +- How to configure the server with `conf.json5`. +- How our codebase is laid out. +- How to run tests and more! + +## That's it for now! + +Everything else in Tachi isn't seeking external contribution at the moment. So, feel free to check +out one of the above linked guides! + diff --git a/docs/docs/contributing/components/documentation.md b/docs/docs/contributing/components/documentation.md new file mode 100644 index 000000000..b8d9dd1ca --- /dev/null +++ b/docs/docs/contributing/components/documentation.md @@ -0,0 +1,52 @@ +# Documentation Guide + +The documentation component of Tachi powers the website you're currently viewing. Hi! + +## Tool Knowledge + +To properly contribute to the documentation, you'll need to know the following things: + +- [The Terminal](../tools/terminal.md) +- [Git](../tools/git.md) + +If you don't know, or aren't comfortable with all of the things on this list, click on them to learn about them! + +## Software Overview + +We use [MKDocs Material](https://squidfunk.github.io/mkdocs-material/) for our documentation. +It extends markdown a bit to let us add things like admonitions and references. + +This is a Python package, making it the only part of our codebase that is Python based. As such, you'll need a way of installing python packages. + +Their documentation is **incredibly** good, so check their stuff out there if you want to use their markdown extensions. + +Other than that, our documentation is vanilla [markdown](https://www.markdownguide.org/basic-syntax/). If you know how to write a reddit comment, you know how to write documentation. + +## Dependencies + +Use `pip` to install `mkdocs` and `mkdocs-material`. + +!!! danger + [Python package management is an utter disasterous mess](https://stackoverflow.com/questions/48941116/does-python-pip-have-the-equivalent-of-nodes-package-json). Feel free to set up a venv or some other elaborate rube-goldberg machine to ensure that your packages don't bleed everywhere. + + Either way, you want to install such that is `mkdocs` on your terminal. + + You might have to restart your terminal after installing it, depending on the alignment of `pip` with the sun. + +## Running the Documentation + +Use `mkdocs serve` inside the `docs/` folder to start up a local documentation viewer on port `8000`. + +This will automatically refresh when you edit anything related to the documentation, so you can quickly see how your stuff goes. + +## A bit about mkdocs.yml + +MKDocs has only one configuration file -- `mkdocs.yml`. This is a [YAML](https://en.wikipedia.org/wiki/YAML) file that configures the documentation we output. + +It also manages the order of pages on the site. **You need to edit this if you're adding new pages! They aren't automatically added!** + +## Contributing Back + +It's just documentation. Make the changes and commit them up, ideally with `docs:` as the commit prefix. + +That is to say: your commit messages should look like `docs: fixed typo in API route`. \ No newline at end of file diff --git a/docs/docs/contributing/components/issues.md b/docs/docs/contributing/components/issues.md new file mode 100644 index 000000000..9c71e168b --- /dev/null +++ b/docs/docs/contributing/components/issues.md @@ -0,0 +1,31 @@ +# GitHub Issues Guide + +This isn't really a Tachi component, but it's important enough to have a guide. + +We use GitHub issues for all of our issue tracking and feature planning, if you're looking to request a feature or report a bug, good etiquette is defined here. + +## Etiquette + +Be nice. + +If you're reporting a bug, **be as explicit as possible**. If something crashed, what were you doing at the time of the crash? Remember that a human has to read your post and attempt to diagnose the issue. + +For the same reasons that you wouldn't go to a doctor and just say "It hurts", you can't just report a software issue as "It's broken". Low effort and ambiguous bug reports will be closed. + +## Large Feature Requests + +If you've came up with an idea for a new large feature, that's awesome! Before you post it though, think it through for a while. +I personally find it very helpful to think on ideas in the shower, but basically anything where you can think about an idea undistracted is useful (like a walk or something). + +This will help you shape up the feature, and makes it easier for maintainers to implement said feature (Especially if it's major). + +Regardless, once you've posted a large feature request, expect there to be discussion in the thread. You should check your emails! + +## Existing Issues + +Search for existing issues before opening a new one. There might already be one open with a similar thing. + +## That's it! + +Don't fret too much about writing perfect issues, but put some effort into them. The development team look at everything that comes through, and will tidy up bits of your issue for you if you make a mistake. + diff --git a/docs/docs/contributing/overview.md b/docs/docs/contributing/overview.md index 93ac07d6d..4eaee9737 100644 --- a/docs/docs/contributing/overview.md +++ b/docs/docs/contributing/overview.md @@ -22,101 +22,16 @@ That's where you step in - people who actually actively *play* games on Tachi! B know about things going on in your game - and even contributing things yourself - you help make their life easier and Tachi's support for your favourite game even better! -## What can I contribute to? -Now for the fun part. In order of difficulty, here are the components of Tachi you can reasonably -contribute to! -All of these sections summarise a part of Tachi, and end with a link to a guide you can use to -contribute to it. +## For Novices... -!!! important - All of the guides linked are understandable by **complete** beginners. Don't worry if you don't - know the first thing about what a "Pull Request" is. - - Hell, `zkldi` didn't know what one of those was until mid-2020. +The Novice guides also cover things like how to get a proper code editing setup, how to use the terminal, and more. - We all have to start somewhere, and our guides are designed for everyone. +You should be able to follow these *even if* you don't know the first thing about programming! -### Issue Reports +All of the novice guides are further down in this page. -You can report issues on the [GitHub](https://github.com/TNG-Dev/Tachi) repository. This requires -*absolutely no programming knowledge* on your part. All you have to do is write up a nice summary -of the bug. +## Sounds good. -!!! note - Although they're called GitHub *issues*, they're actually used for tracking anything. If you've - came up with a cool feature idea, send it over as an issue! `zkldi` will read and Triage them. - -For more information, read our [Issue Reporting Guide](./issues.md). - -### Documentation - -We store our documentation as a series of markdown files in the [Main Repository](https://github.com/TNG-Dev/Tachi). - -Writing, maintaining and proofreading the documentation is something that is **severely** neglected -at the moment. Simple things like typo fixes, all the way up to writing new explanations about major features -are **thoroughly** appreciated, as `zkldi` prioritises maintaining the core of working code. - -If you're interested in this, check out the [Documentation Contribution Guide](./docs.md). - -It'll teach you `shell` and `git` basics, -setting up a programming environment for Tachi, -and how to use our documentation builder. - -### Database Seeds - -We use an interesting system for parts of our database. We actually store a game's songs and charts *in* -our GitHub repository! That means you can: - -- Open the `songs` file for a game. -- Edit a `title` of a song that has a typo. -- Add a couple new songs that were added in the latest update -- Submit your changes back and if they're accepted... -- They automatically synchronise with the site! - -!!! important - This part of Tachi is the most important part for external contributors. - You guys know these games better than `zkldi` does, and you guys keep an eye on all the updates for your games! - - If people don't add songs/charts to this database, `zkldi` will **not** keep an eye on the game for you! Someone *has* to pick up the reigns for each game! - - If you want to add/fix songs, charts, folders or tables for your favourite game - **START HERE!** - - Or in general, if you just want to contribute and don't know what to -- **this is the MOST in need of help. Always.** - -Want to get started on contributing to the Database? Check out our [Database Contribution Guide](./database.md). - -It'll teach you `shell` and `git` basics, -setting up a programming environment for Tachi, -`json`, -and we'll even do a little scripting as a treat! - -### Server, Client - -The server and client form the powerful *core* of Tachi. - -The server handles all of our logic -- How do we get scores, where should scores come from, how do we calculate all these stats and way more. - -The client tries to then place a slick UI over that logic and its exposed API. - -!!! warning - Tachi's core is not an amazingly complex beast, but it is *not* going to be reasonably followable - with 0 programming experience. You'll need some background in programming to be able to do much in - this section. - - That said, we still have a thorough guide -- It's not *from 0*, but it is *from some programming knowledge*. - -Want to get started on contributing to the Core? Check out our [Core Contribution Guide](./core.md). - -We'll cover... - -- Running a local development instance of Tachi. -- How to configure the server with `conf.json5`. -- How our codebase is laid out. -- How to run tests and more! - -## That's it for now! - -Everything else in Tachi isn't seeking external contribution at the moment. So, feel free to check -out one of the above linked guides! \ No newline at end of file +Awesome! Start with the [Setup](./setup.md) guide. This will get Tachi running on your local PC, so you can test all your changes. \ No newline at end of file diff --git a/docs/docs/contributing/setup.md b/docs/docs/contributing/setup.md new file mode 100644 index 000000000..3cb81ae1a --- /dev/null +++ b/docs/docs/contributing/setup.md @@ -0,0 +1,197 @@ +# Setting up a Local Development Environment + +Before you can contribute to Tachi, it'll help to have a functional setup on your machine. + +You don't *necessarily* need to have a working install to contribute - you could easily +make documentation contributions without having anything running on your machine - but +it's extremely helpful to be able to run Tachi's things while working on them. + +## 0. Unix Necessary! + +You *must* be on some Unix-Like operating system. That ideally means means Linux, MacOS or WSL. + +!!! info + This is because of Redis, mainly. We also depend on the `sendmail` binary to send emails around, which might be even less portable. + + Also - we use Linux in production, and your local + environment should be as close to production as reasonably possible. + +### I'm on Windows, help! + +Don't worry. You can run Linux as a subsystem inside Windows, without any virtual machine +nonsense. It's a bit of a headache to get sorted, but Microsoft provide a decent [setup guide](https://docs.microsoft.com/en-us/windows/wsl/install-win10). + +!!! note + You can pick your own Linux distro to use when setting up WSL2. I **highly** recommend + using Ubuntu or Debian for this. They're the most battle tested distributions for WSL2. + + **Kali Linux is NOT Ubuntu.** Don't use it. + +### I'm on Mac. + +Everything should work out of the box. + +### I'm on Linux. + +Tachi has been tested on Ubuntu, Debian, Arch and Manjaro. There's no reason it won't run on any Linux variant, but +if you're running something willfully obtuse like Artix or Slackware, you'll probably hit problems. Figure it out yourself. + +The happiest path for the below guide is for Arch/Manjaro users. For other distros, you +might find getting some of the services running a bit cumbersome. Ah well. + +## 0.5. Get some developer tools. + +If you're an experienced programmer, you won't need this bit. + +### Editor + +You'll need an editor to work in! + +If you've only done a bit of programming in school, +you might be used to something like Visual Studio. + +Sadly, Visual Studio is *not* a great editor for a codebase like Tachi. Visual Studio is +really good at writing C# (a language we don't use at all), +but its integration with TypeScript (the language we use) is quite poor. + +We **highly** recommend that you get [VSCode](https://code.visualstudio.com/). Especially +if you're a beginner! It's an extremely good editor, and has remarkably good integration +with everything we use. + +### Terminal + +You'll need a terminal to run commands in. For Linux and Mac users, you can just open +a Terminal app. + +However, for Windows users we recommend installing the [Windows Terminal](https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701?hl=en-gb&gl=GB). It integrates well with WSL2, which is what you'll have to use. + +Anyway, with a terminal open you can proceed to the next steps! + +## 1. Getting Node, PNPM and Docker. + +You'll need `node` to run JavaScript code on your machine. Our codebase is wrote in JS, so this is pretty important. + +This will also install a command called `npm`, which lets us install libraries. We use a lot of libraries - mainly to handle things like interfacing our code with a database, or serving data over the internet. + +```sh +# debian, ubuntu, other derivatives. +sudo apt-get install nodejs + +# arch, manjaro, other derivatives. +sudo pacman -S nodejs + +# MacOS +brew install node +``` + +!!! info + `Tachi` has only been used on NodeJS versions 14 through 17. In production, we use Node 16. You probably should too. + + To have multiple NodeJS versions on the same device, use a tool like [n](https://www.npmjs.com/package/n). + +We use `pnpm` instead of `npm`. To get `pnpm`, you'll need to run: + +```sh +# You might need `sudo` to run this command. +npm install -g pnpm +``` + +We use MongoDB and Redis as databases, these external databases require radically different instructions for setup depending on what OS/Linux variant you're on. + +As such, we're going to take the lazy route and use something called [Docker](https://docs.docker.com/get-docker/). Get that installed on your PC, and we'll just run the databases inside there. + +!!! info + Docker is like a VM[^1]. It runs an entire Linux box to contain your software in, and generally sidesteps the whole "works on my machine" problem, by just shipping the entire machine. + +## 2. Fork and pull the repo. + +!!! info + You'll need a [GitHub](https://github.com) account. + + They're free - make one if you don't have one! + +Since you can't just commit straight to someone elses codebase (that would be a massive security issue), you need to make a fork of Tachi - One owned by you! + +Go to [the Tachi repository](https://github.com/TNG-dev/Tachi) and click the Fork button in the top right. + +Now, back to the terminal: + +!!! tip + It's good organisation to make a folder on your PC for codestuffs. + + If you do that, make sure you open the terminal in that folder, + so your Tachi repo will save there! + +```sh +# This will create a folder called Tachi on your PC. +# It'll do it wherever your terminal is currently open in. +git clone https://github.com/YOUR_GITHUB_USERNAME/Tachi + +# Open this repository in VSCode! +code Tachi +``` + +## 3. Start the databases. + +Before we bootstrap, lets get the databases started. + +```sh +# Run this at the top of the Tachi repository +# (where the `docker-compose.yml` file is)** +docker compose up --detach +``` + +## 4. Bootstrap! + +!!! warning + The bootstrap script is a fairly recent addition. + + If you have any issues with it, please report them! + +Using a terminal, run `_scripts/bootstrap.sh`. This will "bootstrap" your install of Tachi, and load +everything you need. + +!!! danger + The bootstrap script you just ran created some local self-signed HTTPS certificates. + + Browsers (rightfully) tell you that these are not actually secure HTTPS certs. + We need them for local development, though. + + You **need** to navigate to your running instance of the server in a browser, and tell + the browser that you trust these certificates. Otherwise, all client requests to + the server will silently be chomped by the browser. + +## 5. That's it! + +You now have a fully working instance of Tachi on your PC. You can now start to tinker +with all of its various components. + +To check everything's gone soundly, run `pnpm start-server` and `pnpm start-client`. + +!!! tip + You can use the `+` inside the VSCode terminal to spawn multiple terminals. + + Remember that `Ctrl-C` will kill the currently active process. You should use that + to stop the server or client. + +You should then be able to navigate to https://127.0.0.1:8080, accept the certificates, +and view the client on https://127.0.0.1:3000. + +## 6. Editor Plugins + +If you're using VSCode as your editor (I *really* recommend it!) You'll want a couple +plugins. + +Namely, Install the ESLint plugin, and enable "Format On Save" in your settings. We use an [incredibly strict](https://github.com/CadenceJS/Cadence) plugin for ESLint, which catches a *ton* of programming errors and mistakes. By having it run in your editor, you can see your mistakes before you ever run the code, and have them automatically fix on save! + +!!! tip + With `Ctrl-Shift-P`, you can open VSCodes "Command Palette". This will let you search + for all the possible things VSCode can do. To open the settings, you can use `Ctrl-Shift-P` and search for "Settings". + + It's ridiculously convenient, and there's a bunch of other stuff that VSCode helps with. + +## 7. OK, Now what. + +Now that you've got a working version of Tachi running on your local PC, you should go check out the [component-specific contribution guides](./components.md)! + +[^1]: Docker is not actually a VM, it's significantly smarter and does some Linux jail cgroup nonsense. All you need to care about is that it works like having a separate Linux system on your host system. diff --git a/docs/docs/contributing/tools/terminal.md b/docs/docs/contributing/tools/terminal.md new file mode 100644 index 000000000..6d72fb8d5 --- /dev/null +++ b/docs/docs/contributing/tools/terminal.md @@ -0,0 +1,367 @@ +# Terminal Guide + +!!! info + This is an excerpt/early draft from The Long Guide, a guide `zkldi` is writing to + teach people programming from zero. Feedback is very much appreciated. + + As a result, this is also wrote in a far less Tachi-specific tone. + + The Long Guide also makes liberal use of "Detours". These paragraphs provide context + or history for the things that are going on. Reading them will help! + +The terminal is **the most important** tool to know as a programmer. That might sound like a bold claim, but **everything** you want a computer to do is done via the terminal - graphical interfaces are typically just buttons that hide terminal commands. + +When it comes to programming tools, we typically *don't* make graphical interfaces for our tools. As such, it's necessary to learn the terminal to be able to launch your tools! + +In this guide, we'll cover the terminal - one of **the most important** pieces of kit you'll use. + +## Operating System Stuffs + +This guide is intended for a Unix system - that's Linux, MacOS or [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install). + +For Windows users, this can be a bit of a pain to get set up with. If you're not comfortable installing the Windows Subsystem for Linux, you can always run Linux in a VM. + +### Detour: Virtual Machine + +If you're opting to install Linux in a virtual machine, Ubuntu maintain a [straightforward guide](https://ubuntu.com/tutorials/how-to-run-ubuntu-desktop-on-a-virtual-machine-using-virtualbox#1-overview) for getting a Virtual Machine up and running. + +Once you've got a Unix system available, we can get started! + +### Detour: What's wrong with the Windows Command Line? + +In short, Windows is the only major OS that isn't derived from something called Unix. + +In long, a history lesson: + +Unix is an **old** operating system - as in, it started development before the moon landing. +It was developed primarily by Ken Thompson and Dennis Ritchie; these guys also made the C programming language, which Unix was almost entirely wrote in. + +It was designed for programmers (well, they were the only people really using computers in the 70s), and grew very popular in those circles. As a result, *to this day*, most programming tools are developed using Unix's tools with a Unix environment. + +Unix's influence on computing *cannot* be understated, but Unix itself is not ran much anymore. + +MacOS is derived from Unix, and Linux is similarly so. + +Windows - however - comes from an entirely different family tree: MS-DOS. As such, the Windows environment is different in a bunch of significant ways. + +Of course for regular users, this doesn't matter - they're hardly tinkering with internals! +But for programmers, the differences are *very* significant. Everything from what command lists the files in a folder, to *what a filename even is* is different. + +Due to this, and Unix's programmer-centric design, Windows is a second-class citizen to a lot of programming tools. + +## Opening the Terminal + +Your operating system will come with a "Terminal" application. + +On MacOS, this is called `Terminal.app`. + +On Windows, you can install [Windows Terminal](https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701?hl=en-gb&gl=GB). It has significantly better integration with WSL, which you'll need to follow this guide. + +On Linux, there are many available terminal. Generally, searching for `Terminal` in your list of installed applications should come up with atleast one. If you're using a Linux system on your main PC. + +Open a terminal, and we'll get started running some commands! + +## Files, Folders, Paths + +As you might've guessed, the terminal is *text only*. There's no pointing and clicking, and there's no buttons to click on. + +However, very often in the terminal (or in code!), we'll be interacting with files and folders, and navigating the filesystem! + +So before we dive right in, let's talk for a bit about the idea of files and folders. + +Hell, this chapter might seem like a meaningless diversion, you've used files and folders all the time! However, properly understanding folders and files is **crucial** to understanding the terminal. + +## Folders + +Folders are the simplest thing to understand. A folder contains files, or more folders. + +``` +My Documents/ + Work Documents/ + some-code.js + cv.docx + + poems.txt +``` + +In the above example, `My Documents` is a folder that contains two items: + +- A *file* called `poems.txt` +- and another folder called `Work Documents`, which contains some more stuff. + +## Files + +Files contain *data*. This is a tad complex, but for the time being all we need to know is this: + +- A file's extension is just a suggestion. It has no bearing on the content of the file. + +Lets say we have a file called `file.pdf`. +If we rename it to `file.mp3`, the *data* inside the file actually stays *exactly the same*. + +Of course, trying to listen to it in an mp3 player won't work, but if you were to `Open With...` that `.mp3` with something that views `.pdf`s, it will load perfectly fine! + +We'll actually prove this later, so keep this in mind! + +- A file just stores data. + +### Detour: How do we go from bytes to text? + +!!! note + If you're not familiar with hexadecimal (or binary), [a quick rundown is available here](http://www.emulator101.com/introduction-to-binary-and-hex.html). + +You might already know that computers can only store 0s and 1s. How do we go from 0s and 1s as bytes into text we can read? + +Well, we have *literally* assigned a number to every single character in every single alphabet. + +No, seriously. It's called Unicode, and you can [check it out.](https://www.fileformat.info/info/charset/UTF-8/list.htm) + +When a program wants to display a file as text (notepad, a code editor, etc.), it goes through every byte in the file and converts it using that above table. + +So technically, when you store `hello world!` in a file, +it's actually storing `68 65 6c 6c 6f 20 77 6f 72 6c 64 21 0a`. + +A hex value of `68` corresponds to `h`, `65` corresponds to `e`... and so on! + +!!! note + For further reading, Tom Scott has an *excellent* video on this, [check it out](https://www.youtube.com/watch?v=MijmeoH9LT4). + +## Filepaths + +We want to refer to files on our computer in text form. This is *really* common if you're writing code that reads a file, or doing *literally anything* in a terminal. + +There are two kinds of file paths: + +### Absolute + +Absolute filepaths are defined from the *root* (like, the top level folder) of the filesystem, and **always start with a slash (`/`)**. + +As an example, the path `/home/someone/Documents/file.txt` refers to the file located at: +``` +home/ + someone/ + Documents/ + file.txt +``` + +These are great, but they can get cumbersome. If I'm doing stuff in my documents folder, I don't want to start all of my filepaths with `/home/someone/Documents/whatever_file_i_want_to_work_on`! + +### Relative + +Relative file paths are *relative* to the folder you're currently in. **They can start with anything, but NEVER a slash (`/`)**. + +As an example, lets say I'm working in the `/home/someone` folder. I want to refer to the same file as above: I could do it with the path `Documents/file.txt`. + +We can also refer to files *outside* of the folder we're currently working in. A file called `..` is special, it means "go up a folder". + +In our case, if I wanted to open the file `/home/someone_else/file.txt`, and I was still working in the `/home/someone` folder, I could do it with the path `../someone_else/file.txt`! + +## OK, enough noise, lets get writing commands. + +Open a terminal, if you don't have one open already. + +The first word you write in a terminal is the program you wish to run. On a Unix system, most useful programs are stored in the `/bin` folder. + +Let's check what type of operating system we're running on, using the `/bin/uname` command. + +```sh +/bin/uname +``` + +Great! This should have output some text back into your terminal. It's not very useful, but it's a good sanity check. + +Every word after the command you write is passed to the program. For example, `/bin/touch` creates a file at the path provided. + +```sh +/bin/touch some_file +``` + +`/bin/ls` will list all of the files in the folder we're currently in. Do that to see your newly created file! + +Let's put some content into it. Find this file on your system (you can use `/bin/pwd` to find out what folder your terminal is open in), and put some text into it using a notepad app. + +!!! tip + You can also use notepads inside the terminal - the proper term for them is "Text Editor", because, well, they edit text! + + `/bin/nano` is one of the more intuitive terminal text editors. You can use that to + write some data into your file, then use `Ctrl-O` to save, and `Ctrl-X` to quit. + + If those keybindings seem arcane to you, it's because `nano` is from the 1980s. + +Once you've got some data in the file, use `/bin/cat` to read the data. + +```sh +/bin/cat some_file +``` + +Finally, we can use `cd` to move around the filesystem (to `c`hange `d`irectories). Interestingly, `cd` is *not* a command stored on the filesystem, but is actually *built in* to the shell. It's weird, and we'll understand it better later. + +```sh +# Change what folder we're in to the root of the filesystem. +cd / + +# you can use /bin/ls to list what files and folders are here. +/bin/ls + +# ...and cd into one of them! +cd home +``` + +Excellent. This covers moving around in the terminal and poking around with files. + +## Echoes, Variables + +`/bin/echo` is a seemingly useless command. It repeats what you say to it. + +```sh +/bin/echo hello world! +``` + +This will just spit out "hello world!" exactly as you wrote it. This program has to be useless, right? Nope. It's actually *really* helpful. + +Let's talk about variables. In the shell, variables are a name that you can assign a value to. + +Let's create a variable called `NAME` which contains our name. We do that with the `=` operator. + +```sh +# The lack of space between NAME and = is significant. Otherwise, it tries to read it as +# running a program called NAME. The shell is old, and stupid. +NAME=yourname +``` + +We can then use echo to spit this variable back out. By using a `$`, we state that the following text is a variable, and should spit out that variable's value instead! +```sh +/bin/echo My name is... $NAME +``` + +This should spit out your name! + +Of course, this isn't mighty useful. However, variables *are* useful to the programs we run. Programs can actually acce + +Not all variables have to be defined by us. Some are defined by the shell itself. One of those, is `$PATH`. + +Wanna check all the variables set right now on your system? Use `/bin/env`. + +## No more /bin/ + +Ok, I'll come clean. I've been making you do something the hard way for a while now. Nobody writes out `/bin/` before every single command. Can you *imagine* how tiring that would be? +Well, you don't have to, since I made you do it up until this point. + +Nope, instead, the shell uses a variable called `$PATH` to do some lookup magic. + +Let's read what's in `$PATH`. + +```sh +/bin/echo $PATH +``` + +Interesting. It's a bunch of file paths, but with `:` splitting them up. + +You might get some output that looks like this. +``` +/usr/local/sbin:/bin:/usr/local/bin:/usr/bin: +``` + +`$PATH` is a special variable, and the shell listens to it. It's actually more like an automatic prefix for commands. + +When you refer to a program in the shell, it checks *all* of the folders defined in `$PATH` to see if it has a program called whatever you looked for. So actually, we can just write... + +```sh +ls + +# instead of /bin/ls all the time! +``` + +And the shell will check `/usr/local/sbin/ls`. If there's an `ls` there, it will run it. If not, it will try the next one, `/bin/ls`. +We know that exists, and it'll run perfectly fine! + +If it doesn't find the requested command anywhere in those folders, it'll error. Try it by running a command that definitely doesn't exist, like `scrimbly`. + +```sh +scrimbly +# bash: scrimbly: command not found +``` + +## What commands actually exist? + +Well, it depends on what's installed on your system, but we actually know enough about +the shell to figure this out ourselves! + +Lets use `ls` to list the files in all those folders in `$PATH`! + +```sh +ls /bin +``` + +should tell us a *buuunch* of files. That's already a hell of a lot of commands! + +You can use `man COMMAND_NAME` to learn more about a command. You can also just google about it, as `man` info tends to be a little... obtuse. + +Also, commands you run in the terminal aren't *just* limited to things that output text. + +You can run something like `firefox` (or `safari`/`chrome`). That really will open an instance of your browser! + +Remember, literally *all* programs can be ran by the shell! + +!!! tip + If you actually just launched a browser, you might notice that your terminal is in use. + + You can break out of this in a couple of ways. + + You can close the browser, and you'll get the prompt to type a command back. + + Alternatively, while in the terminal, you can hit `Ctrl-C`. This will *kill* the currently running process in the terminal, and should give you a prompt back. + + This is useful for a bunch of commands that don't exit on their own, like `top`. + +## Flags + +As one last thing, lets talk about flags. These aren't actually special to the shell in any way, but it's more of a convention. + +Programs typically support something called flags, which allow you to change what the program does. + +These come in two forms. Short form flags look like `-l`, and long form flags start with two hyphens, and typically have longer names, like `--list` + +For example, we've used `ls` quite a bit to list files. But what if we wanted to list all of the files vertically, rather than horizontally? + +```sh +# This will list all the things in `/` horizontally. +ls / + +# This passes a flag called l to ls. This will result in the output being vertical. +ls -l / +``` + +OK, this is bizarre. How were you ever supposed to know that? Well, typical convention is that if a program is passed `-h` or `--help`, it'll give you help (`h` for help, right?), and list all the flags. + +Let's just write `ls -h` to get some help aaand... + +Uh. It didn't give us any help. + +Here's another important takeaway. **Some programs don't follow conventions.** + +No worries, let's use `ls --help`. + +Oh boy, that sure is a lot of information. If you scroll up a bit, you should be able to see all the flags that `ls` can take. There's a *hell* of a lot, and I personally only know about three of them. + +## That's the basics! + +That wasn't too bad, but the shell is a slightly confusing beast at times. I mean, it's been around since the 70s. It's had a lot of time to accumulate dust and mess. + +## Summary + +- A filepath refers to a file on your PC. +- An absolute filepath starts with `/`, like `/home/users/robert/file.txt`. +- A relative path looks like `robert/file.txt`, and is relative to the folder you're currently working in. +- You can "go up a folder" with `..`, like `../joey/file.txt`. This will go up a folder, then get `joey/file.txt`, relative to where it is now. +- You can go up a folder as much as you want. `../../../../foo/bar.txt`. + +And as for the shell... + +- You can use `ls` to list files, and `cd` change what folder your terminal is in. +- You can use flags like `-s` and `--scrimble` after writing a command to modify what it does a bit. +- Everything wrote after the program is passed to the program, so `echo hello!` will result in `hello!` being passed to `echo`. +- You can run literally anything from the shell, like `firefox`. +- To kill the thing you're running and get back to the prompt, you can use `Ctrl-C`. +- You can set variables in the shell, and read them with `$VARIABLE_NAME`. + +This is more than enough info to be able to use and navigate around comfortably in the terminal. There's still a lot more complexity to the shell, but for now, this is enough! \ No newline at end of file diff --git a/docs/docs/index.md b/docs/docs/index.md index 09feab9f2..d5a5be743 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -34,6 +34,13 @@ to it. See the [Contribution Guide](./contributing/overview.md)! ***** +## Programmer References + +These sections are for experienced programmers who want to see documentation on how +Tachi's components work internally and externally. + +If you're looking to contribute to Tachi, check out the [Contribution Guide](./contributing/overview.md). + ### API Reference This is for people who want to make things with Tachi's API, and assumes basic knowledge of @@ -55,7 +62,7 @@ This is for people who want to work on the `Tachi-Bot`. View it [here](./tachi-bot/overview.md). -### User Reference +### Wiki This is for end user reference, such as score importing tutorials, documentation on tachi's statistics. It requires no programming knowledge, and is mostly used as a wiki-like reference. diff --git a/docs/docs/tachi-server/contributing.md b/docs/docs/tachi-server/contributing.md deleted file mode 100644 index 461e56021..000000000 --- a/docs/docs/tachi-server/contributing.md +++ /dev/null @@ -1,34 +0,0 @@ -# Contributing To Tachi Server - -If you want to contribute to Tachi, that's really appreciated! - -Most of the time, Tachi is a one-man operation, so -any help is really appreciated. - -***** - -## Codebase Contributions - -`tachi-server` is the core of the logic behind tachi, and -is open sourced under AGPLv3. - -Contributions to this will be under increased scrutiny as -I am trying to keep the codebase well organised and tidy. - -!!! tip - If you're setting up a development environment locally, - commit `47c981f` converted the codebase from spaces to tabs. - This revision is hidden using .git-blame-ignore-revs. - - You can fix it with this command. - ``` - git config blame.ignoreRevsFile .git-blame-ignore-revs - ``` - - !!! warning - This only works on git 2.23 or greater. Your package manager may not have a version - this recent. See [Git Installation for Linux](https://git-scm.com/download/linux). - -!!! warning - Your code should follow the branching setup we have. - You can read about it [here](../infrastructure/branches). diff --git a/docs/docs/tachi-server/setup/setup.md b/docs/docs/tachi-server/setup/setup.md deleted file mode 100644 index 772ce9c96..000000000 --- a/docs/docs/tachi-server/setup/setup.md +++ /dev/null @@ -1 +0,0 @@ -OUTDATED \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 86a4d1793..6635588e1 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -23,11 +23,20 @@ theme: name: Switch to dark mode nav: - - Introduction: "index.md" - - Contributing: - - "contributing/overview.md" + - Getting Started: + - "index.md" + - Contributing: + - "contributing/overview.md" + - "contributing/setup.md" + - "contributing/components.md" + - Component-Specific Guides: + - "contributing/components/issues.md" + - "contributing/components/documentation.md" - - User Reference: + - Tooling Guides: + - "contributing/tools/terminal.md" + + - Wiki: - "user/overview.md" - "user/rules.md" - "user/games.md"