diff --git a/apps/octo-contribution-docs/docs/getting-started/getting-started.mdx b/apps/octo-contribution-docs/docs/getting-started/getting-started.mdx new file mode 100644 index 00000000..c1a09faf --- /dev/null +++ b/apps/octo-contribution-docs/docs/getting-started/getting-started.mdx @@ -0,0 +1,74 @@ +--- +sidebar_position: 2 +title: Getting Started +--- + +import RootProjectStructure from './img/root-project-structure.png'; + +## Requirements +* **Node.js version** 16.0 or above. + * However, documentation websites `apps/*-docs` run on docusaurus, + which requires Node.js version to be `18.0` or above. + * So, **Node.js version `18.0`** or above is recommended. + * **`npm`** is the preferred package manager. +* **IDE** + * Some developers prefer WebStorm, and some VSCode. There are other good options out there as well. + As long as the quality of commits meets the minimum standard, choice of IDE is of no concern. + * However, you will find more support for `WebStorm` in this documentation than any other IDE. + +## Project Structure +
+ +
+ This is the [root](https://github.com/quadnix/octo) of the project. + Octo is a **monorepo**, i.e. all relevant files lives here. + And we use **`nx`** as the base library to facilitate the monorepo. + + There is usually a huge debate between monorepo vs polyrepo, but after much consideration, + we felt having all code in one location outweighs most of the cons, and enforces common standards, + such as eslint, dictionary, and tsconfig, just to name a few. + + The repository, at first glance, might look huge, but really is just a collection of small packages and apps, + all working independently, with their separate CICD pipelines and life cycles. They just live together, + like a little family they are. +
+
+ +
+There is a lot to unpack here, but to get started here some important directories and files. +* `apps`: is where we currently house all the documentation websites. They are `docusaurus` projects, +i.e. React and Markdown files. +* `packages` is where you will find Octo's distributable packages. + * `octo` is the base package. + * `octo-aws-cdk` is our AWS implementation of Octo. + * `octo-build` is the CLI tool to build Octo packages. +* `.eslintrc.cjs`: is the base EsLint file. We use EsLint to enforce code linting. +* `.prettierrc`: is the base Prettier file. We use Prettier to enforce code formatting. +* `dictionary.dic`: is the spell check file. +* Rest of the directories and files are not where you might spend much time. +They are still tersely discussed later in this documentation. + +## Code Style & Guidelines +* We follow [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html) for the entire project. +There are some minor differences where we deviate, but we expect to keep this list short. + * Column limit (120): our lines can be 120 character long as opposed to 80. This applies to all files in this project. +* We keep anything sorted, where applicable, e.g. json files, object keys, configurations, etc. +* We enforce a spell checker via EsLint. If the word is not recognized, it must have an entry in dictionary.dic + +## Documentation +The role of documentation in any organization cannot be overstated, and we are no exception. +We don't believe in great documentation, but we do expect to write documents consistently. +The idea behind two sets of documentation is to capture the feature documentation, +and also to capture the decisions leading up to the feature. + +If our contributors and developers feels "lost" and don't understand the changes they are about to commit, +or how things work, then the documentation has failed them. + +Another important factor to consider while documenting, is to keep the context in perspective. +The aim is to teach, and not to document. + +## Testing +* We use `Jest` for writing tests. Unit, Integration, and E2E tests are supported. +* `packages/*` are covered with tests. Documentation websites don't have tests. +* We aim to test features, not lines of code. This might not mean 100% test coverage, which is okay. +The idea is if the implementation of a feature changes, the tests (apart from mocks) don't change. diff --git a/apps/octo-contribution-docs/docs/getting-started/img/root-project-structure.png b/apps/octo-contribution-docs/docs/getting-started/img/root-project-structure.png new file mode 100644 index 00000000..8fb10b2a Binary files /dev/null and b/apps/octo-contribution-docs/docs/getting-started/img/root-project-structure.png differ diff --git a/apps/octo-contribution-docs/docs/intro.md b/apps/octo-contribution-docs/docs/intro.md deleted file mode 100644 index 45e8604c..00000000 --- a/apps/octo-contribution-docs/docs/intro.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Tutorial Intro - -Let's discover **Docusaurus in less than 5 minutes**. - -## Getting Started - -Get started by **creating a new site**. - -Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**. - -### What you'll need - -- [Node.js](https://nodejs.org/en/download/) version 18.0 or above: - - When installing Node.js, you are recommended to check all checkboxes related to dependencies. - -## Generate a new site - -Generate a new Docusaurus site using the **classic template**. - -The classic template will automatically be added to your project after you run the command: - -```bash -npm init docusaurus@latest my-website classic -``` - -You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. - -The command also installs all necessary dependencies you need to run Docusaurus. - -## Start your site - -Run the development server: - -```bash -cd my-website -npm run start -``` - -The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. - -The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/. - -Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes. diff --git a/apps/octo-contribution-docs/docs/introduction/introduction.md b/apps/octo-contribution-docs/docs/introduction/introduction.md new file mode 100644 index 00000000..71b0aa9e --- /dev/null +++ b/apps/octo-contribution-docs/docs/introduction/introduction.md @@ -0,0 +1,18 @@ +--- +sidebar_position: 1 +title: Introduction +--- + +🎉 Welcome!! + +We are excited for you to be here, and thank you for considering to contribute to Octo. +This documentation is dedicated to help you get started to make contributions and to not feel "lost". +Here you might find information on contribution guidelines, tech stack, project structure, and much more. + +[//]: # (TODO: Insert Octo-Docs home page URL here.) +:::tip +Counterintuitively, you might not find much information on the internal workings of Octo here. +This documentation is solely dedicated to help make contributions, not to learn Octo itself. +
Though in order to make contributions, you need to understand the fundamentals of Octo, +and so if you haven't already, you should check out. +::: diff --git a/apps/octo-contribution-docs/docs/root/_category_.json b/apps/octo-contribution-docs/docs/root/_category_.json new file mode 100644 index 00000000..066bbc58 --- /dev/null +++ b/apps/octo-contribution-docs/docs/root/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "", + "position": 3, + "link": { + "type": "generated-index" + } +} diff --git a/apps/octo-contribution-docs/docs/root/git/git.md b/apps/octo-contribution-docs/docs/root/git/git.md new file mode 100644 index 00000000..bfd264cb --- /dev/null +++ b/apps/octo-contribution-docs/docs/root/git/git.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 1 +title: Git & GitHub +--- + +We use `Git` as our version control tool, and `GitHub` as the UI. + +## Commit Messages & PR +Because we are a monorepo, the GitHub space is shared with multiple projects. +We must take precaution while merging commits to ensure we understand which project we are talking about. + +Individual commit messages don't matter, since the PR you create will be "Squash and Merge". +The `name` and `description` of the PR, however, must be properly formatted. + +## Issues, Features, & Bug Tracking +* **TODO**: Create a TODO, as a comment, in code when the issue is small. It is something to remind yourself to do. +* **GitHub Issue**: Create a GitHub issue for large features, and bugs. This is where discussions will happen. diff --git a/apps/octo-contribution-docs/docs/root/husky/husky.md b/apps/octo-contribution-docs/docs/root/husky/husky.md new file mode 100644 index 00000000..03c3f14c --- /dev/null +++ b/apps/octo-contribution-docs/docs/root/husky/husky.md @@ -0,0 +1,29 @@ +--- +sidebar_position: 2 +title: Husky & Git Hooks +--- + +[Husky](https://typicode.github.io/husky/) is a widely used tool to enforce Git hooks. +Before we make any commit, husky enables us to run hooks that check the "correctness" of the commit. + +## Setup +* Added to `package.json` under `devDependencies`, and under `scripts`. +* For first time contributors, you need to run `npm run prepare` script to initialize husky. +* A `/.husky/_` directory is created with some husky scripts. +* From this point, husky automagically runs and verifies your commits. + +:::danger +You must try to never ignore the husky hooks. Always prefer to fix the issues first, or ask for help. + +To ignore verification, you can use the `no-verify` git option, +> git commit --no-verify -m "commit message" +::: + +## Configuration +Our husky pre-commit hooks looks like, +```shell +#!/bin/sh + +npm run lint +``` +i.e. we only run the `lint` script as our commit verification. diff --git a/apps/octo-contribution-docs/docs/tutorial-basics/_category_.json b/apps/octo-contribution-docs/docs/tutorial-basics/_category_.json index 2e6db55b..192f1ee9 100644 --- a/apps/octo-contribution-docs/docs/tutorial-basics/_category_.json +++ b/apps/octo-contribution-docs/docs/tutorial-basics/_category_.json @@ -1,6 +1,6 @@ { "label": "Tutorial - Basics", - "position": 2, + "position": 4, "link": { "type": "generated-index", "description": "5 minutes to learn the most important Docusaurus concepts." diff --git a/apps/octo-contribution-docs/src/css/custom.scss b/apps/octo-contribution-docs/src/css/custom.scss index 2bc6a4cf..f3c8df68 100644 --- a/apps/octo-contribution-docs/src/css/custom.scss +++ b/apps/octo-contribution-docs/src/css/custom.scss @@ -28,3 +28,15 @@ --ifm-color-primary-lightest: #4fddbf; --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3); } + +.layout_text_wrap_image { + overflow: scroll; + img { + float: left; + margin: 5px; + } + + div { + text-align: justify; + } +} diff --git a/dictionary.dic b/dictionary.dic index 1ef87a74..5fbb3da5 100644 --- a/dictionary.dic +++ b/dictionary.dic @@ -51,7 +51,10 @@ mdx nacl nginx octo +octo's octob +polyrepo +prettierrc proj promisify quadnix diff --git a/docs/editor/vscode/settings.json b/docs/editor/vscode/settings.json new file mode 100644 index 00000000..9753358f --- /dev/null +++ b/docs/editor/vscode/settings.json @@ -0,0 +1,17 @@ +{ + "breadcrumbs.enabled": false, + "editor.fontFamily": "Office Code Pro", + "editor.fontSize": 14, + "editor.minimap.enabled": false, + "editor.rulers": [120], + "editor.scrollBeyondLastLine": false, + "editor.wordWrapColumn": 120, + "explorer.confirmDelete": false, + "extensions.ignoreRecommendations": true, + "files.insertFinalNewline": true, + "workbench.colorCustomizations": { + "editor.selectionBackground": "#ca5cb4", + "editor.selectionHighlightBackground": "#7F0C6B" + }, + "workbench.tree.indent": 25 +}