From db47440d470ea6a6e100b620b10d078c01314992 Mon Sep 17 00:00:00 2001 From: undergroundwires Date: Sun, 30 Jan 2022 13:15:34 +0100 Subject: [PATCH] Improve existing documentation Improve documentation for different markdown documentation files. Goal is to simplify and make the language and content more clear. --- CONTRIBUTING.md | 67 +++++++++++++++++++++++++++----------------- README.md | 48 +++++++++++++++---------------- docs/architecture.md | 8 ++---- docs/ci-cd.md | 38 +++++++++++++++++++++---- docs/development.md | 6 ++-- docs/templating.md | 51 +++++++++++++++++---------------- docs/tests.md | 51 ++++++++++++++++++--------------- 7 files changed, 158 insertions(+), 111 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 20b12993..941eac9f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,34 +1,51 @@ # Contributing -- Love your input! Contributing to this project should be as easy and transparent as possible, whether it's: - - Reporting a bug - - Discussing the current state of the code - - Submitting a fix - - Proposing new features - - Becoming a maintainer +Love your input! Contributing to this project should be as easy and transparent as possible, whether it's: + +- reporting a bug, +- discussing the current state of the code, +- submitting a fix, +- proposing new features, +- or becoming a maintainer. + +As a small open source project with small community, it can sometimes take a long time to address the issues so please be patient. ## Pull request process -- [GitHub flow](https://guides.github.com/introduction/flow/index.html) with [GitOps](./img/architecture/gitops.png) is used -- Your pull requests are actively welcomed. -- The steps: - 1. Fork the repo and create your branch from master. - 2. If you've added code that should be tested, add tests. - 3. If you've changed APIs, update the documentation. - 4. Ensure the test suite passes. - 5. Make sure your code lints. - 6. Issue that pull request! -- 🙏 DO - - Document your changes in the pull request -- ❗ DON'T - - Do not update the versions, current version is only [set by the maintainer](./img/architecture/gitops.png) and updated automatically by [bump-everywhere](https://github.com/undergroundwires/bump-everywhere) +Your pull requests are actively welcomed. We collaborate using [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow). -## License +The steps: + +1. Fork the repo and create your branch from master. +2. If you've added code that requires testing, add tests. See [tests.md](./docs/tests.md). +3. If you've done a major change, update the documentation. See [docs/](./docs/). +4. Ensure the test suite passes. See [development.md | Testing](./docs/development.md#testing) for commands. +5. Make sure your code lints.See [development.md | Linting](./docs/development.md#linting) for commands. +6. Issue that pull request! + +**🙏 DO:** + +- Document why (what you're trying to solve) rather than what in the pull request. + +**❗ DON'T:** -By contributing, you agree that your contributions will be licensed under its [GNU General Public License v3.0](./LICENSE). +- Do not update the versions, current version is [set by the maintainer](./docs/ci-cd.md#gitops) and updated automatically by [bump-everywhere](https://github.com/undergroundwires/bump-everywhere). -## Read more +Automated pipelines will run to control your PR and they will publish your code once the maintainer merges your PR. + +📖 You can read more in [ci-cd.md](./docs/ci-cd.md). + +## Extend scripts + +Here's quick information for you who want to add more scripts. + +You have two alternatives: + +1. [Create an issue](https://github.com/undergroundwires/privacy.sexy/issues/new/choose) and ask for someone else to add the script for you. +2. Or send a PR yourself. This would make it faster to get your code into the project. You need to add scripts to related OS in [collections](src/application/collections/) folder. Then you'd sent a pull request, see [pull request process](#pull-request-process). + - 📖 If you're unsure about the syntax, check [collection-files.md](docs/collection-files.md). + - 📖 If you wish to use templates, use [templating.md](./docs/templating.md). + +## License -- See [tests](./docs/tests.md) for testing -- See [extend script](./README.md#extend-scripts) for quick steps to extend scripts -- See [architecture overview](./docs/architecture.md) to deep dive into privacy.sexy codebase +By contributing, you agree that your [GNU General Public License v3.0](./LICENSE) will be the license for your contributions. diff --git a/README.md b/README.md index ba198322..bed356a0 100644 --- a/README.md +++ b/README.md @@ -97,39 +97,35 @@ ## Get started -- Online version at [https://privacy.sexy](https://privacy.sexy) - - 💡 No need to run any compiled software on your computer. -- Alternatively download offline version for [Windows](https://github.com/undergroundwires/privacy.sexy/releases/download/0.11.3/privacy.sexy-Setup-0.11.3.exe), [macOS](https://github.com/undergroundwires/privacy.sexy/releases/download/0.11.3/privacy.sexy-0.11.3.dmg) or [Linux](https://github.com/undergroundwires/privacy.sexy/releases/download/0.11.3/privacy.sexy-0.11.3.AppImage). - - 💡 Single click to execute your script. -- ❗ Come back regularly to apply latest version for stronger privacy and security. +- 🌍️ **Online**: [https://privacy.sexy](https://privacy.sexy). +- 🖥️ **Offline**: Check [releases page](https://github.com/undergroundwires/privacy.sexy/releases), or download directly for: [Windows](https://github.com/undergroundwires/privacy.sexy/releases/download/0.11.2/privacy.sexy-Setup-0.11.2.exe), [macOS](https://github.com/undergroundwires/privacy.sexy/releases/download/0.11.2/privacy.sexy-0.11.2.dmg), [Linux](https://github.com/undergroundwires/pr.vacy.sexy/releases/download/0.11.2/privacy.sexy-0.11.2.AppImage). -[![privacy.sexy application](img/screenshot.png?raw=true)](https://privacy.sexy) +Online version does not require to run any software on your computer. Offline version has more functions such as running the scripts directly. -## Why +💡 You should apply your configuration from time to time (more than once). It would strengthen your privacy and security control because privacy.sexy and its scripts get better and stronger in every new version. -- Rich tweak pool to harden security & privacy of the OS and other software on it -- Free (both free as in beer and free as in speech) -- No need to run any compiled software that has access to your system, just run the generated scripts -- Have full visibility into what the tweaks do as you enable them -- Ability to revert (undo) applied scripts -- Everything is transparent: both application and its infrastructure are open-source and automated -- Easily extendable with [own powerful templating language](./docs/templating.md) -- Each script is independently executable without cross-dependencies +[![privacy.sexy application](img/screenshot.png?raw=true )](https://privacy.sexy) -## Extend scripts +## Features -- You can either [create an issue](https://github.com/undergroundwires/privacy.sexy/issues/new/choose) -- Or send a PR: - 1. Fork the repository - 2. Add more scripts in respective script collection in [collections](src/application/collections/) folder. - - 📖 If you're unsure about the syntax you can refer to the [collection files | documentation](docs/collection-files.md). - - 🙏 For any new script, please add `revertCode` and `docs` values if possible. - 3. Send a pull request 👌 +- **Rich**: Hundreds of scripts that aims to give you control of your data. +- **Free**: Both free as in "beer" and free as in "speech". +- **Transparent**. Have full visibility into what the tweaks do as you enable them. +- **Reversible**. Revert if something feels wrong. +- **Accessible**. No need to run any compiled software on your computer with web version. +- **Open**. What you see as code in this repository is what you get. The application itself, its infrastructure and deployments are open-source and automated thanks to [bump-everywhere](https://github.com/undergroundwires/bump-everywhere). +- **Tested.** A lot of tests. Automated and manual. Community-testing and verification. Stability improvements comes before new features. +- **Extensible**. Effortlessly [extend scripts](./CONTRIBUTING.md#extend-scripts) with a custom designed [templating language](./docs/templating.md). +- **Portable and simple**. Every script is independently executable without cross-dependencies. -## Development +## Contributing + +Contributions of any type are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) as starting point, it includes useful information like [how to add new scripts](./CONTRIBUTING.md#extend-scripts). -See [development.md](./docs/development.md) for Docker usage, running/building application, development best-practices along with other information related to development of this project. +## Development -## Architecture +Refer to [development.md](./docs/development.md) for Docker usage and reading more about setting up your development environment. Check [architecture.md](./docs/architecture.md) for an overview of design and how different parts and layers work together. You can refer to [application.md](./docs/application.md) for a closer look at application layer codebase and [presentation.md](./docs/presentation.md) for code related to GUI layer. [collection-files.md](./docs/collection-files.md) explains the YAML files that are the core of the application and [templating.md](./docs/templating.md) documents how to use templating language in those files. In [ci-cd.md](./docs/ci-cd.md), you can read more about the pipelines that automates maintenance tasks and ensures you get what see. + +[docs/](./docs/) folder includes all other documentation. diff --git a/docs/architecture.md b/docs/architecture.md index f9c97851..e3bce184 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -59,10 +59,8 @@ This project includes [GitHub Actions](../.github/workflows/) to automatically p ## GitOps -CI/CD is fully automated using different Git events and GitHub actions. This repository uses [bump-everywhere](https://github.com/undergroundwires/bump-everywhere) to automate versioning, tagging, creation of [`CHANGELOG.md`](./../CHANGELOG.md) and GitHub releases. A dedicated [workflow](./../.github/workflows/release.desktop.yaml) creates desktop installers and executables and attaches them into GitHub releases. +CI/CD pipelines automate operational tasks based on different Git events. [bump-everywhere](https://github.com/undergroundwires/bump-everywhere) enables this automation. -Everything that's merged in the master goes directly to production. +📖 Read more in [`ci-cd.md`](./ci-cd.md#gitops). -📖 Refer to [ci-cd.md](./ci-cd.md) to read more on CI/CD pipelines. - -[![CI/CD to AWS with GitHub Actions](../img/architecture/gitops.png)](../.github/workflows/) +[![CI/CD using GitHub Actions](../img/architecture/gitops.png)](../.github/workflows/) diff --git a/docs/ci-cd.md b/docs/ci-cd.md index 0c92c31b..747b7ef5 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -1,10 +1,26 @@ -# Pipelines +# CI/CD overview -Pipelines are found under [`.github/workflows`](./../.github/workflows). +## GitOps + +CI/CD is fully automated using different Git events and GitHub actions. This repository uses [bump-everywhere](https://github.com/undergroundwires/bump-everywhere) to automate versioning, tagging, creation of `CHANGELOG.md` and GitHub releases. A dedicated workflow [release.desktop.yaml](./../.github/workflows/release.desktop.yaml) creates desktop installers and executables and attaches them into GitHub releases. + +Everything that's merged in the master goes directly to production. + +[![CI/CD using GitHub Actions](./../img/architecture/gitops.png)](../.github/workflows/) + +## Pipeline files + +privacy.sexy uses [GitHub actions](https://github.com/features/actions) to define and run pipelines as code. + +GitHub workflows i.e. pipelines exist in [`/.github/.workflows/`](./../.github/workflows/) folder without any subfolders due to GitHub actions requirements [1] . + +[1]: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#about-yaml-syntax-for-workflows ## Pipeline types -They are categorized based on their type: +We categorize pipelines into different categories. We use these names in convention when naming files and actions, see [naming conventions](#naming-conventions). + +The categories consist of: - `tests`: Different types of tests to verify functionality. - `checks`: Other controls such as vulnerability scans or styling checks. @@ -12,8 +28,18 @@ They are categorized based on their type: ## Naming conventions -Pipeline files are named using: **`..yaml`**. +Convention for naming pipeline files: **`..yaml`**. + +**`type`**: + +- Sub-folders do not work for GitHub workflows [1] so we use `.` prefix to organize them. +- See also [pipeline types](#pipeline-types) for list of all usable types. + +**`name`**: -**`type`**: Sub-folders do not work for GitHub workflows so that's why `.` prefix is used. See also [pipeline types](#pipeline-types). +- We name workflows using kebab-case. +- E.g. file name `tests.unit.yaml`, pipeline file should set the naem as: `name: unit-tests`. +- Kebab-case allows to have better URL references to them. + - [README.md](./../README.md) uses URL references to show status badges for actions. -**`name`**: Pipeline themselves are named using kebab case. It allows for easier URL references for their status badges. E.g. file name `tests.unit.yaml`, pipeline name: `name: unit-tests` +[1]: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#about-yaml-syntax-for-workflows diff --git a/docs/development.md b/docs/development.md index e1962dd3..af3e7143 100644 --- a/docs/development.md +++ b/docs/development.md @@ -5,7 +5,7 @@ Before your commit, a good practice is to: 1. [Run unit tests](#testing) 2. [Lint your code](#linting) -You could run other types of tests as well, but they may take longer time and overkill for your changes. All tests are executed inside a pull request. +You could run other types of tests as well, but they may take longer time and overkill for your changes. Automated actions executes the tests for a pull request or change in the main branch. See [ci-cd.md](./ci-cd.md) for more information. ## Commands @@ -22,6 +22,8 @@ You could run other types of tests as well, but they may take longer time and ov - Interactive mode with GUI: `npm run test:e2e` - Headless mode without GUI: `npm run test:e2e -- --headless` +📖 Read more about testing in [tests](./tests.md). + ### Linting - Lint all (recommended 💡): `npm run lint` @@ -48,4 +50,4 @@ You could run other types of tests as well, but they may take longer time and ov You should use EditorConfig to follow project style. -For Visual Studio Code, recommended extensions are defined in [`.vscode/extensions.json`](./../.vscode/extensions.json). +For Visual Studio Code, [`.vscode/extensions.json`](./../.vscode/extensions.json) includes list of recommended extensions. diff --git a/docs/templating.md b/docs/templating.md index 7f7eef4d..5352edf1 100644 --- a/docs/templating.md +++ b/docs/templating.md @@ -3,14 +3,15 @@ ## Benefits of templating - Generating scripts by sharing code to increase best-practice usage and maintainability. -- Creating self-contained scripts without depending on each other that can be easily shared. +- Creating self-contained scripts without cross-dependencies. - Use of pipes for writing cleaner code and letting pipes do dirty work. ## Expressions -- Expressions in the language are defined inside mustaches (double brackets, `{{` and `}}`). -- Expression syntax is inspired mainly by [Go Templates](https://pkg.go.dev/text/template). -- Expressions are used in and enabled by functions where they can be used. +- Expressions start and end with mustaches (double brackets, `{{` and `}}`). + - E.g. `Hello {{ $name }} !` +- Syntax is close to [Go Templates ❤️](https://pkg.go.dev/text/template) that has inspired this templating language. +- Functions enables usage of expressions. - In script definition parts of a function, see [`Function`](./collection-files.md#Function). - When doing a call as argument values, see [`FunctionCall`](./collection-files.md#Function). @@ -55,34 +56,36 @@ A function can call other functions such as: ### with -- Skips the block if the variable is absent or empty. -- Binds its context (`.`) value of provided argument for the parameter if provided one. -- A block is defined as `{{ with $parameterName }} Parameter value is {{ . }} here {{ end }}`. -- The parameters used for `with` condition should be declared as optional, otherwise `with` block becomes redundant. -- Example: +Skips its "block" if the variable is absent or empty. Its "block" is between `with` start (`{{ with .. }}`) and end (`{{ end }`}) expressions. E.g. `{{ with $parameterName }} Hi, I'm a block! {{ end }}`. - ```yaml - function: FunctionThatOutputsConditionally - parameters: - - name: 'argument' - optional: true - code: |- - {{ with $argument }} - Value is: {{ . }} - {{ end }} - ``` +Binds its context (`.`) value of provided argument for the parameter if provided one. E.g. `{{ with $parameterName }} Parameter value is {{ . }} here {{ end }}`. + +💡 Declare parameters used for `with` condition as optional. Set `optional: true` for the argument if you use it like `{{ with $argument }} .. {{ end }}`. + +Example: + +```yaml + function: FunctionThatOutputsConditionally + parameters: + - name: 'argument' + optional: true + code: |- + {{ with $argument }} + Value is: {{ . }} + {{ end }} +``` ### Pipes -- Pipes are set of functions available for handling text in privacy.sexy. +- Pipes are functions available for handling text. - Allows stacking actions one after another also known as "chaining". -- Just like [Unix pipelines](https://en.wikipedia.org/wiki/Pipeline_(Unix)), the concept is simple: each pipeline's output becomes the input of the following pipe. -- Pipes are provided and defined by the compiler and consumed by collection files. -- Pipes can be combined with [parameter substitution](#parameter-substitution) and [with](#with). +- Like [Unix pipelines](https://en.wikipedia.org/wiki/Pipeline_(Unix)), the concept is simple: each pipeline's output becomes the input of the following pipe. +- You cannot create pipes. [A dedicated compiler](./application.md#parsing-and-compiling) provides pre-defined pipes to consume in collection files. +- You can combine pipes with other expressions such as [parameter substitution](#parameter-substitution) and [with](#with) syntax. - ❗ Pipe names must be camelCase without any space or special characters. - **Existing pipes** - `inlinePowerShell`: Converts a multi-lined PowerShell script to a single line. - - `escapeDoubleQuotes`: Escapes `"` characters to be used inside double quotes (`"`) + - `escapeDoubleQuotes`: Escapes `"` characters, allows you to use them inside double quotes (`"`). - **Example usages** - `{{ with $code }} echo "{{ . | inlinePowerShell }}" {{ end }}` - `{{ with $code }} echo "{{ . | inlinePowerShell | escapeDoubleQuotes }}" {{ end }}` diff --git a/docs/tests.md b/docs/tests.md index c7e552e0..21443b79 100644 --- a/docs/tests.md +++ b/docs/tests.md @@ -1,23 +1,28 @@ # Tests -- There are two different types of tests executed: - 1. [Unit tests](#unit-tests) - 2. [Integration tests](#integration-tests) - 3. [End-to-end (E2E) tests](#e2e-tests) -- All tests - - Uses [Mocha](https://mochajs.org/) and [Chai](https://www.chaijs.com/). - - Are written in files that includes `.spec` extension. -- 💡 You can use path/module alias `@/tests` in import statements. +There are different types of tests executed: + +1. [Unit tests](#unit-tests) +2. [Integration tests](#integration-tests) +3. [End-to-end (E2E) tests](#e2e-tests) + +Common aspects for all tests: + +- They use [Mocha](https://mochajs.org/) and [Chai](https://www.chaijs.com/). +- Their files end with `.spec.{ts|js}` suffix. + +💡 You can use path/module alias `@/tests` in import statements. ## Unit tests -- Tests each component in isolation. -- Defined in [`./tests/unit`](./../tests/unit). +- Unit tests test each component in isolation. +- All unit tests goes under [`./tests/unit`](./../tests/unit). +- They rely on [stubs](./../tests/unit/shared/Stubs) for isolation. ### Unit tests structure - [`./src/`](./../src/) - - Includes code that will be tested tested. + - Includes source code that unit tests will test. - [`./tests/unit/`](./../tests/unit/) - Includes test code. - Tests follow same folder structure as [`./src/`](./../src). @@ -29,7 +34,7 @@ - Asserting functions should start with `expect` prefix. - [`TestCases/`](./../tests/unit/shared/TestCases/) - Shared test cases. - - Test runner functions that uses `it()` from Mocha test [Mocha test framework](https://mochajs.org/) should be prefixed with `it.` + - Functions that calls `it()` from [Mocha test framework](https://mochajs.org/) should have `it` prefix. - E.g. `itEachAbsentCollectionValue()`. - [`Stubs/`](./../tests/unit/shared/Stubs) - Includes stubs to be able to test components in isolation. @@ -38,39 +43,39 @@ ### Unit tests naming - Each test suite first describe the system under test. - - E.g. tests for class `Application` is categorized under `Application`. -- Tests for specific methods are categorized under method name (if applicable). - - E.g. test for `run()` is categorized under `run`. + - E.g. tests for class `Application.ts` are all inside `Application.spec.ts`. +- `describe` blocks tests for same function (if applicable). + - E.g. test for `run()` are inside `describe('run', () => ..)`. ### Act, arrange, assert - Tests use act, arrange and assert (AAA) pattern when applicable. - **Arrange** - - Should set up the test case. + - Sets up the test case. - Starts with comment line `// arrange`. - **Act** - - Should cover the main thing to be tested. + - Executes the actual test. - Starts with comment line `// act`. - **Assert** - - Should elicit some sort of response. + - Elicit some sort of expectation. - Starts with comment line `// assert`. ## Integration tests - Tests functionality of a component in combination with others (not isolated). - Ensure dependencies to third parties work as expected. -- Defined in [`./tests/integration`](./../tests/integration). +- Defined in [./tests/integration](./../tests/integration). ## E2E tests - Test the functionality and performance of a running application. -- E2E tests are configured by vue plugin [`e2e-cypress`](https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli-plugin-e2e-cypress#readme) for Vue CLI. -- Names and folders are structured logically based on tests. +- Vue CLI plugin [`e2e-cypress`](https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli-plugin-e2e-cypress#readme) configures E2E tests. +- Test names and folders have logical structure based on tests executed. - The structure is following: - [`cypress.json`](./../cypress.json): Cypress configuration file. - [`./tests/e2e/`](./../tests/e2e/): Base Cypress folder. - - [`/specs/`](./../tests/e2e/specs/): Test files, test are named with `.spec.js` extension. - - [`/plugins/index.js`](./../tests/e2e/plugins/index.js): Plugin file executed before project is loaded. + - [`/specs/`](./../tests/e2e/specs/): Test files named with `.spec.js` extension. + - [`/plugins/index.js`](./../tests/e2e/plugins/index.js): Plugin file executed before loading project. - [`/support/index.js`](./../tests/e2e/support/index.js): Support file, runs before every single spec file. - *(Ignored)* `/videos`: Asset folder for videos taken during tests. - *(Ignored)* `/screenshots`: Asset folder for Screenshots taken during tests.