44r0n7/privacy.sexy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve existing documentation

Browse Source 
Improve documentation for different markdown documentation files. Goal
is to simplify and make the language and content more clear.
This commit is contained in:
undergroundwires
2022-01-30 13:15:34 +01:00
parent 1bcc6c8b2b
commit db47440d47
7 changed files with 159 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
CONTRIBUTING.md
View File

@@ -1,34 +1,51 @@
# Contributing # Contributing
- Love your input! Contributing to this project should be as easy and transparent as possible, whether it's: 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 - reporting a bug,
- Submitting a fix - discussing the current state of the code,
- Proposing new features - submitting a fix,
- Becoming a maintainer - 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 ## 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. We collaborate using [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow).
- Your pull requests are actively welcomed.
- The steps: The steps:
1. Fork the repo and create your branch from master.
2. If you've added code that should be tested, add tests. 1. Fork the repo and create your branch from master.
3. If you've changed APIs, update the documentation. 2. If you've added code that requires testing, add tests. See [tests.md](./docs/tests.md).
4. Ensure the test suite passes. 3. If you've done a major change, update the documentation. See [docs/](./docs/).
5. Make sure your code lints. 4. Ensure the test suite passes. See [development.md | Testing](./docs/development.md#testing) for commands.
6. Issue that pull request! 5. Make sure your code lints.See [development.md | Linting](./docs/development.md#linting) for commands.
- 🙏 DO 6. Issue that pull request!
- Document your changes in the pull request
- ❗ DON'T **🙏 DO:**
- 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)
- Document why (what you're trying to solve) rather than what in the pull request.
**❗ DON'T:**
- 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).
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 ## License
By contributing, you agree that your contributions will be licensed under its [GNU General Public License v3.0](./LICENSE). By contributing, you agree that your [GNU General Public License v3.0](./LICENSE) will be the license for your contributions.
## Read more
- 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

48
README.md
View File

@@ -97,39 +97,35 @@
## Get started ## Get started
- Online version at [https://privacy.sexy](https://privacy.sexy) - 🌍️ **Online**: [https://privacy.sexy](https://privacy.sexy).
- 💡 No need to run any compiled software on your computer. - 🖥️ **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).
- 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.
[![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 [![privacy.sexy application](img/screenshot.png?raw=true )](https://privacy.sexy)
- 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
## Extend scripts ## Features
- You can either [create an issue](https://github.com/undergroundwires/privacy.sexy/issues/new/choose) - **Rich**: Hundreds of scripts that aims to give you control of your data.
- Or send a PR: - **Free**: Both free as in "beer" and free as in "speech".
1. Fork the repository - **Transparent**. Have full visibility into what the tweaks do as you enable them.
2. Add more scripts in respective script collection in [collections](src/application/collections/) folder. - **Reversible**. Revert if something feels wrong.
- 📖 If you're unsure about the syntax you can refer to the [collection files | documentation](docs/collection-files.md). - **Accessible**. No need to run any compiled software on your computer with web version.
- 🙏 For any new script, please add `revertCode` and `docs` values if possible. - **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).
3. Send a pull request 👌 - **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.
## 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).
## Development ## Development
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. Refer to [development.md](./docs/development.md) for Docker usage and reading more about setting up your development environment.
## Architecture
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. 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.

8
docs/architecture.md
View File

@@ -59,10 +59,8 @@ This project includes [GitHub Actions](../.github/workflows/) to automatically p
## GitOps ## 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 using GitHub Actions](../img/architecture/gitops.png)](../.github/workflows/)
[![CI/CD to AWS with GitHub Actions](../img/architecture/gitops.png)](../.github/workflows/)

38
docs/ci-cd.md
View File

@@ -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 ## 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. - `tests`: Different types of tests to verify functionality.
- `checks`: Other controls such as vulnerability scans or styling checks. - `checks`: Other controls such as vulnerability scans or styling checks.
@@ -12,8 +28,18 @@ They are categorized based on their type:
## Naming conventions ## Naming conventions
Pipeline files are named using: **`<type>.<name>.yaml`**. Convention for naming pipeline files: **`<type>.<name>.yaml`**.
**`type`**: Sub-folders do not work for GitHub workflows so that's why `<type>.` prefix is used. See also [pipeline types](#pipeline-types). **`type`**:
**`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` - Sub-folders do not work for GitHub workflows [1] so we use `<type>.` prefix to organize them.
- See also [pipeline types](#pipeline-types) for list of all usable types.
**`name`**:
- 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.
[1]: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#about-yaml-syntax-for-workflows

6
docs/development.md
View File

@@ -5,7 +5,7 @@ Before your commit, a good practice is to:
1. [Run unit tests](#testing) 1. [Run unit tests](#testing)
2. [Lint your code](#linting) 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 ## 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` - Interactive mode with GUI: `npm run test:e2e`
- Headless mode without GUI: `npm run test:e2e -- --headless` - Headless mode without GUI: `npm run test:e2e -- --headless`
📖 Read more about testing in [tests](./tests.md).
### Linting ### Linting
- Lint all (recommended 💡): `npm run lint` - 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. 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.

51
docs/templating.md
View File

@@ -3,14 +3,15 @@
## Benefits of templating ## Benefits of templating
- Generating scripts by sharing code to increase best-practice usage and maintainability. - 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. - Use of pipes for writing cleaner code and letting pipes do dirty work.
## Expressions ## Expressions
- Expressions in the language are defined inside mustaches (double brackets, `{{` and `}}`). - Expressions start and end with mustaches (double brackets, `{{` and `}}`).
- Expression syntax is inspired mainly by [Go Templates](https://pkg.go.dev/text/template). - E.g. `Hello {{ $name }} !`
- Expressions are used in and enabled by functions where they can be used. - 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). - 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). - 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 ### with
- Skips the block if the variable is absent or empty. 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 }}`.
- 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:
```yaml Binds its context (`.`) value of provided argument for the parameter if provided one. E.g. `{{ with $parameterName }} Parameter value is {{ . }} here {{ end }}`.
function: FunctionThatOutputsConditionally
parameters: 💡 Declare parameters used for `with` condition as optional. Set `optional: true` for the argument if you use it like `{{ with $argument }} .. {{ end }}`.
- name: 'argument'
optional: true Example:
code: |-
{{ with $argument }} ```yaml
Value is: {{ . }} function: FunctionThatOutputsConditionally
{{ end }} parameters:
``` - name: 'argument'
optional: true
code: |-
{{ with $argument }}
Value is: {{ . }}
{{ end }}
```
### Pipes ### 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". - 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. - 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. - You cannot create pipes. [A dedicated compiler](./application.md#parsing-and-compiling) provides pre-defined pipes to consume in collection files.
- Pipes can be combined with [parameter substitution](#parameter-substitution) and [with](#with). - 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. - ❗ Pipe names must be camelCase without any space or special characters.
- **Existing pipes** - **Existing pipes**
- `inlinePowerShell`: Converts a multi-lined PowerShell script to a single line. - `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** - **Example usages**
- `{{ with $code }} echo "{{ . | inlinePowerShell }}" {{ end }}` - `{{ with $code }} echo "{{ . | inlinePowerShell }}" {{ end }}`
- `{{ with $code }} echo "{{ . | inlinePowerShell | escapeDoubleQuotes }}" {{ end }}` - `{{ with $code }} echo "{{ . | inlinePowerShell | escapeDoubleQuotes }}" {{ end }}`

51
docs/tests.md
View File

@@ -1,23 +1,28 @@
# Tests # Tests
- There are two different types of tests executed: There are different types of tests executed:
1. [Unit tests](#unit-tests)
2. [Integration tests](#integration-tests) 1. [Unit tests](#unit-tests)
3. [End-to-end (E2E) tests](#e2e-tests) 2. [Integration tests](#integration-tests)
- All tests 3. [End-to-end (E2E) tests](#e2e-tests)
- Uses [Mocha](https://mochajs.org/) and [Chai](https://www.chaijs.com/).
- Are written in files that includes `.spec` extension. Common aspects for all tests:
- 💡 You can use path/module alias `@/tests` in import statements.
- 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 ## Unit tests
- Tests each component in isolation. - Unit tests test each component in isolation.
- Defined in [`./tests/unit`](./../tests/unit). - All unit tests goes under [`./tests/unit`](./../tests/unit).
- They rely on [stubs](./../tests/unit/shared/Stubs) for isolation.
### Unit tests structure ### Unit tests structure
- [`./src/`](./../src/) - [`./src/`](./../src/)
- Includes code that will be tested tested. - Includes source code that unit tests will test.
- [`./tests/unit/`](./../tests/unit/) - [`./tests/unit/`](./../tests/unit/)
- Includes test code. - Includes test code.
- Tests follow same folder structure as [`./src/`](./../src). - Tests follow same folder structure as [`./src/`](./../src).
@@ -29,7 +34,7 @@
- Asserting functions should start with `expect` prefix. - Asserting functions should start with `expect` prefix.
- [`TestCases/`](./../tests/unit/shared/TestCases/) - [`TestCases/`](./../tests/unit/shared/TestCases/)
- Shared test cases. - 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()`. - E.g. `itEachAbsentCollectionValue()`.
- [`Stubs/`](./../tests/unit/shared/Stubs) - [`Stubs/`](./../tests/unit/shared/Stubs)
- Includes stubs to be able to test components in isolation. - Includes stubs to be able to test components in isolation.
@@ -38,39 +43,39 @@
### Unit tests naming ### Unit tests naming
- Each test suite first describe the system under test. - Each test suite first describe the system under test.
- E.g. tests for class `Application` is categorized under `Application`. - E.g. tests for class `Application.ts` are all inside `Application.spec.ts`.
- Tests for specific methods are categorized under method name (if applicable). - `describe` blocks tests for same function (if applicable).
- E.g. test for `run()` is categorized under `run`. - E.g. test for `run()` are inside `describe('run', () => ..)`.
### Act, arrange, assert ### Act, arrange, assert
- Tests use act, arrange and assert (AAA) pattern when applicable. - Tests use act, arrange and assert (AAA) pattern when applicable.
- **Arrange** - **Arrange**
- Should set up the test case. - Sets up the test case.
- Starts with comment line `// arrange`. - Starts with comment line `// arrange`.
- **Act** - **Act**
- Should cover the main thing to be tested. - Executes the actual test.
- Starts with comment line `// act`. - Starts with comment line `// act`.
- **Assert** - **Assert**
- Should elicit some sort of response. - Elicit some sort of expectation.
- Starts with comment line `// assert`. - Starts with comment line `// assert`.
## Integration tests ## Integration tests
- Tests functionality of a component in combination with others (not isolated). - Tests functionality of a component in combination with others (not isolated).
- Ensure dependencies to third parties work as expected. - Ensure dependencies to third parties work as expected.
- Defined in [`./tests/integration`](./../tests/integration). - Defined in [./tests/integration](./../tests/integration).
## E2E tests ## E2E tests
- Test the functionality and performance of a running application. - 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. - Vue CLI plugin [`e2e-cypress`](https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli-plugin-e2e-cypress#readme) configures E2E tests.
- Names and folders are structured logically based on tests. - Test names and folders have logical structure based on tests executed.
- The structure is following: - The structure is following:
- [`cypress.json`](./../cypress.json): Cypress configuration file. - [`cypress.json`](./../cypress.json): Cypress configuration file.
- [`./tests/e2e/`](./../tests/e2e/): Base Cypress folder. - [`./tests/e2e/`](./../tests/e2e/): Base Cypress folder.
- [`/specs/`](./../tests/e2e/specs/): Test files, test are named with `.spec.js` extension. - [`/specs/`](./../tests/e2e/specs/): Test files named with `.spec.js` extension.
- [`/plugins/index.js`](./../tests/e2e/plugins/index.js): Plugin file executed before project is loaded. - [`/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. - [`/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)* `/videos`: Asset folder for videos taken during tests.
- *(Ignored)* `/screenshots`: Asset folder for Screenshots taken during tests. - *(Ignored)* `/screenshots`: Asset folder for Screenshots taken during tests.