mirror of
https://github.com/privacyguides/privacyguides.org.git
synced 2025-07-01 09:12:39 +00:00
docs!: Move most documentation to forum
This commit is contained in:
@ -21,7 +21,7 @@ MAGIC Grants is our fiscal host, and their custom, open-source donation platform
|
||||
Thank you to these organizations who significantly support Privacy Guides. (1)
|
||||
{ .annotate }
|
||||
|
||||
1. Please contact <info@magicgrants.org> to inquire about giving. Privacy Guides reserves the right to rescind the membership of those who are unaligned with our mission or organization at any time. Organizational members have no ability to influence what content is recommended on the Privacy Guides website. Learn more about our [donation acceptance policy](donation-acceptance-policy.md).
|
||||
1. Please contact <info@magicgrants.org> to inquire about giving. Privacy Guides reserves the right to rescind the membership of those who are unaligned with our mission or organization at any time. Organizational members have no ability to influence what content is recommended on the Privacy Guides website. Learn more about our [donation acceptance policy](https://discuss.privacyguides.net/t/ep2-donation-acceptance-policy/27360/1).
|
||||
|
||||
<div class="mdx-specialthanks" markdown>
|
||||
|
||||
@ -82,7 +82,7 @@ You can become an organizational member by reaching out to <info@magicgrants.org
|
||||
|
||||
Organizational members that choose to be recognized publicly are included in our organizational members section (above), and occasionally at other opportunities where appropriate. Organizational member links include the `rel="nofollow"` attribute: We adopted this policy to screen out potential abuse of our program and site to raise the rank of third parties in search algorithms. Unfortunately, this is a growing problem for nonprofits. This was a complex decision since we know many of the sincere supporters behind these companies, but we decided that it was the best choice for us.
|
||||
|
||||
Organizational members have no ability to influence what content is recommended on the Privacy Guides website. Learn more about our [donation acceptance policy](donation-acceptance-policy.md).
|
||||
Organizational members have no ability to influence what content is recommended on the Privacy Guides website. Learn more about our [donation acceptance policy](https://discuss.privacyguides.net/t/ep2-donation-acceptance-policy/27360/1).
|
||||
|
||||
### What is an active membership?
|
||||
|
||||
@ -110,7 +110,7 @@ We use donations for a variety of purposes, including:
|
||||
|
||||
**Online Services**
|
||||
|
||||
: We host [internet services](services.md) for testing and showcasing different privacy-products we like and [recommend](../tools.md). Some of them are made publicly available for our community's use (SearXNG, Tor, etc.), and some are provided for our team members (email, etc.).
|
||||
: We host internet services for testing and showcasing different privacy-products we like and [recommend](../tools.md). Some of them are made publicly available for our community's use (SearXNG, Tor, etc.), and some are provided for our team members (email, etc.).
|
||||
|
||||
**Product Purchases**
|
||||
|
||||
|
||||
@ -1,58 +0,0 @@
|
||||
---
|
||||
title: Donation Acceptance Policy
|
||||
description: Privacy Guides aspires to obtain funding from a wide variety of sources to reduce our dependency on any single donor. Please consider donating!
|
||||
---
|
||||
|
||||
Privacy Guides takes the ethical responsibility of making unbiased recommendations on its website very seriously.
|
||||
|
||||
Privacy Guides aspires to obtain funding from a wide variety of sources to reduce our dependency on any single donor. Please consider [donating](donate.md)!
|
||||
|
||||
## What we **can** accept
|
||||
|
||||
In the course of our regular fundraising activities...
|
||||
|
||||
- Donations and other forms of support will generally be accepted from individuals, corporations, foundations, or other entities, without limitations.
|
||||
- This includes cash, cash equivalents (checks, money orders, credit/debit card payments), and cryptocurrency.
|
||||
- Gifts of Real Property, Personal Property, or Securities may only be accepted upon approval of the MAGIC Grants board of directors.
|
||||
|
||||
Privacy Guides will only accept such gifts that are legal and consistent with our policies. Gifts must not interfere with Privacy Guides' mission, purpose, and procedures.
|
||||
|
||||
## Things we do **not** do
|
||||
|
||||
- Accept sponsorships.
|
||||
- Offer to recommend a product or service in exchange for a donation or other incentive.
|
||||
- Threaten to remove a recommendation for a product or service unless we receive a donation or other incentive.
|
||||
- Offer to expedite a review of a product or service in exchange for a donation or other incentive.
|
||||
- Write sponsored content or feature sponsored components in our content.
|
||||
|
||||
## Things we **may** do
|
||||
|
||||
- Accept donations from privacy-related companies and non-profits.
|
||||
- Apply for grant programs.
|
||||
- Accept free versions of software or hardware to test and review, while being mindful of possible differences in versions that could differ from a regular customer experience. ([More details](executive-policy.md#ep1-freely-provided-product-samples))
|
||||
- Accept discounted versions of software or hardware that assist our operations (for example, discounted software costs made available to non-profits).
|
||||
|
||||
## Restrictions on gifts
|
||||
|
||||
Privacy Guides accepts unrestricted gifts, and we appreciate the flexibility to apply your gift to our programs where they are most needed.
|
||||
|
||||
We also accept and appreciate gifts for specified programs or purposes, provided that such gifts are consistent with our program's stated mission, purpose, and priority. Privacy Guides will not accept gifts which are too restrictive in purpose.
|
||||
|
||||
Examples of gifts which are too restrictive include:
|
||||
|
||||
- Those which fund the research and review of a specific product category or specific product.
|
||||
- Those which violate our existing policies.
|
||||
- Those which are too difficult for us to administer.
|
||||
- Those that are for purposes outside our general mission.
|
||||
|
||||
An example of an acceptable restriction could be a gift towards funding our [video](https://www.privacyguides.org/videos/) production, or hosting our website and forum.
|
||||
|
||||
Final decisions on the restrictive nature of a gift and its acceptance or refusal will be made by our executive committee.
|
||||
|
||||
## Additional terms
|
||||
|
||||
Privacy Guides generally does not pay "finder's fees" or commissions to third parties in connection with any gift to Privacy Guides. We may, however, pay commissions and fees to properly negotiate and receive assets when appropriate.
|
||||
|
||||
No officer, committee member, employee, or other agent of Privacy Guides will be compensated in a manner which is dependent on the size or nature of gifts made to Privacy Guides by any person. If we engage with legal, accounting, or other professionals, their fees and expenses will be determined by the time they spend engaged with our work, and not by reference to any particular gift in connection to their retainer.
|
||||
|
||||
Privacy Guides always follows the MAGIC Grants Gift Acceptance Policy, available on their website: <https://magicgrants.org/about/documentation/>
|
||||
@ -1,26 +0,0 @@
|
||||
---
|
||||
title: Executive Policy
|
||||
description: These are policies formally adopted by our executive committee, and take precedence over all other statements expressed on this website.
|
||||
---
|
||||
|
||||
These are policies formally adopted by Privacy Guides' executive committee, and take precedence over all other statements expressed on this website.
|
||||
|
||||
The keywords **must**, **must not**, **required**, **shall**, **shall not**, **should**, **should not**, **recommended**, **may**, and **optional** are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
|
||||
|
||||
## EP1: Freely-Provided Product Samples
|
||||
|
||||
*Our policy on accepting product samples for review was adopted September 7, 2024.*
|
||||
|
||||
=== "Current Version (1)"
|
||||
|
||||
- Privacy Guides **shall not** proactively reach out to vendors asking for product samples or review accounts.
|
||||
- Privacy Guides **shall not** accept test/review accounts for subscription cloud services.
|
||||
- Privacy Guides **may** accept freely-provided product samples for one-time purchase software applications which run locally, given they don't require a subscription for continued operation.
|
||||
- Privacy Guides **may** accept freely-provided samples of hardware products.
|
||||
- Privacy Guides **may** accept a freely-provided subscription service associated with a hardware product, if such a subscription/license is necessary to use the product.
|
||||
- Privacy Guides **must not** enter into an agreement pertaining to our editorial opinion with the vendor in order to receive a sample or publish a review. All freely-provided items must be strictly "no strings attached."
|
||||
- We **may** agree to return the product to the vendor following the review if requested.
|
||||
- We **may** agree to a reasonable NDA, provided it has a clear embargo date that is lifted no more than 6 months in the future where the NDA completely no longer applies.
|
||||
- We **should not** enter into any other agreement with the vendor not described here. Potential agreements not described here **must** be approved by the executive committee beforehand.
|
||||
|
||||
In all cases, whether we paid for the product independently or received a free sample from a vendor, how we obtained the product **must** be clearly documented in the background section of every article associated with the product.
|
||||
@ -1,33 +0,0 @@
|
||||
---
|
||||
description: We run a number of web services to test out features and promote cool decentralized, federated, and/or open-source projects.
|
||||
---
|
||||
|
||||
# Privacy Guides Services
|
||||
|
||||
We run a number of web services to test out features and promote cool decentralized, federated, and/or open-source projects. Many of these services are available to the public and are detailed below.
|
||||
|
||||
[:material-comment-alert: Report an issue](https://discuss.privacyguides.net/c/services/2){ class="md-button md-button--primary" }
|
||||
|
||||
## Discourse
|
||||
|
||||
- Domain: [discuss.privacyguides.net](https://discuss.privacyguides.net)
|
||||
- Availability: Public
|
||||
- Source: [github.com/discourse/discourse](https://github.com/discourse/discourse)
|
||||
|
||||
## Gitea
|
||||
|
||||
- Domain: [code.privacyguides.dev](https://code.privacyguides.dev)
|
||||
- Availability: Invite-Only. Access may be granted upon request to any team working on *Privacy Guides*-related development or content.
|
||||
- Source: [snapcraft.io/gitea](https://snapcraft.io/gitea)
|
||||
|
||||
## Matrix
|
||||
|
||||
- Domain: [matrix.privacyguides.org](https://matrix.privacyguides.org)
|
||||
- Availability: Invite-Only. Access may be granted upon request to Privacy Guides team members, Matrix moderators, third-party Matrix community administrators, Matrix bot operators, and other individuals in need of a reliable Matrix presence.
|
||||
- Source: [github.com/spantaleev/matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy)
|
||||
|
||||
## SearXNG
|
||||
|
||||
- Domain: [search.privacyguides.net](https://search.privacyguides.net)
|
||||
- Availability: Public
|
||||
- Source: [github.com/searxng/searxng-docker](https://github.com/searxng/searxng-docker)
|
||||
@ -1,294 +0,0 @@
|
||||
---
|
||||
title: Admonitions
|
||||
description: A guide for website contributors on creating admonitions.
|
||||
---
|
||||
|
||||
**Admonitions** (or "call-outs") are a choice writers can use to include side content in an article without interrupting the document flow.
|
||||
|
||||
<div class="admonition example" markdown>
|
||||
<p class="admonition-title">Example Admonition</p>
|
||||
|
||||
This is an example of an admonition. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.
|
||||
|
||||
</div>
|
||||
|
||||
<details class="example" markdown>
|
||||
<summary>Example Collapsible Admonition</summary>
|
||||
|
||||
This is an example of a collapsible admonition. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.
|
||||
|
||||
</details>
|
||||
|
||||
## Formatting
|
||||
|
||||
To add an admonition to a page, you can use the following code:
|
||||
|
||||
```markdown title="Admonition"
|
||||
<div class="admonition TYPE" markdown>
|
||||
<p class="admonition-title">TITLE</p>
|
||||
|
||||
ENCLOSED TEXT
|
||||
|
||||
</div>
|
||||
```
|
||||
|
||||
```markdown title="Collapsible Admonition"
|
||||
<details class="TYPE" markdown>
|
||||
<summary>TITLE</summary>
|
||||
|
||||
ENCLOSED TEXT
|
||||
|
||||
</details>
|
||||
```
|
||||
|
||||
The `TITLE` must be specified, if you don't want a specific title you can set it to the same text as the `TYPE` (see below) in title case, e.g. `Note`. The `ENCLOSED TEXT` should be Markdown formatted.
|
||||
|
||||
### Regular types
|
||||
|
||||
Replace `TYPE` in the examples above with one of the following:
|
||||
|
||||
#### `note`
|
||||
|
||||
<div class="admonition note" markdown>
|
||||
<p class="admonition-title">Note</p>
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
||||
|
||||
</div>
|
||||
|
||||
#### `abstract`
|
||||
|
||||
<div class="admonition abstract" markdown>
|
||||
<p class="admonition-title">Abstract</p>
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
||||
|
||||
</div>
|
||||
|
||||
#### `info`
|
||||
|
||||
<div class="admonition info" markdown>
|
||||
<p class="admonition-title">Info</p>
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
||||
|
||||
</div>
|
||||
|
||||
#### `tip`
|
||||
|
||||
<div class="admonition tip" markdown>
|
||||
<p class="admonition-title">Tip</p>
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
||||
|
||||
</div>
|
||||
|
||||
#### `success`
|
||||
|
||||
<div class="admonition success" markdown>
|
||||
<p class="admonition-title">Success</p>
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
||||
|
||||
</div>
|
||||
|
||||
#### `question`
|
||||
|
||||
<div class="admonition question" markdown>
|
||||
<p class="admonition-title">Question</p>
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
||||
|
||||
</div>
|
||||
|
||||
#### `warning`
|
||||
|
||||
<div class="admonition warning" markdown>
|
||||
<p class="admonition-title">Warning</p>
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
||||
|
||||
</div>
|
||||
|
||||
#### `failure`
|
||||
|
||||
<div class="admonition failure" markdown>
|
||||
<p class="admonition-title">Failure</p>
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
||||
|
||||
</div>
|
||||
|
||||
#### `danger`
|
||||
|
||||
<div class="admonition danger" markdown>
|
||||
<p class="admonition-title">Danger</p>
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
||||
|
||||
</div>
|
||||
|
||||
#### `bug`
|
||||
|
||||
<div class="admonition bug" markdown>
|
||||
<p class="admonition-title">Bug</p>
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
||||
|
||||
</div>
|
||||
|
||||
#### `example`
|
||||
|
||||
<div class="admonition example" markdown>
|
||||
<p class="admonition-title">Example</p>
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
||||
|
||||
</div>
|
||||
|
||||
#### `quote`
|
||||
|
||||
<div class="admonition quote" markdown>
|
||||
<p class="admonition-title">Quote</p>
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
||||
|
||||
</div>
|
||||
|
||||
### Special Types
|
||||
|
||||
#### `recommendation`
|
||||
|
||||
This format is used to generate recommendation cards. Notably it is missing the `<p class="admonition-title">` element.
|
||||
|
||||
``` markdown title="Recommendation Card"
|
||||
<div class="admonition recommendation" markdown>
|
||||
|
||||
{ align=right }
|
||||
|
||||
**PhotoPrism** is a self-hostable platform for managing photos. It supports album syncing and sharing as well as a variety of other [features](https://photoprism.app/features). It does not include E2EE, so it's best hosted on a server that you trust and is under your control.
|
||||
|
||||
[:octicons-home-16: Homepage](https://photoprism.app){ .md-button .md-button--primary }
|
||||
[:octicons-eye-16:](https://photoprism.app/privacy){ .card-link title="Privacy Policy" }
|
||||
[:octicons-info-16:](https://photoprism.app/kb){ .card-link title=Documentation}
|
||||
[:octicons-code-16:](https://github.com/photoprism){ .card-link title="Source Code" }
|
||||
|
||||
<details class="downloads" markdown>
|
||||
<summary>Downloads</summary>
|
||||
|
||||
- [:simple-github: GitHub](https://github.com/photoprism)
|
||||
|
||||
</details>
|
||||
|
||||
</div>
|
||||
```
|
||||
|
||||
<div class="result" markdown>
|
||||
|
||||
<div class="admonition recommendation" markdown>
|
||||
|
||||
{ align=right }
|
||||
|
||||
**PhotoPrism** is a self-hostable platform for managing photos. It supports album syncing and sharing as well as a variety of other [features](https://photoprism.app/features). It does not include E2EE, so it's best hosted on a server that you trust and is under your control.
|
||||
|
||||
[:octicons-home-16: Homepage](https://photoprism.app){ .md-button .md-button--primary }
|
||||
[:octicons-eye-16:](https://photoprism.app/privacy){ .card-link title="Privacy Policy" }
|
||||
[:octicons-info-16:](https://photoprism.app/kb){ .card-link title=Documentation}
|
||||
[:octicons-code-16:](https://github.com/photoprism){ .card-link title="Source Code" }
|
||||
|
||||
<details class="downloads" markdown>
|
||||
<summary>Downloads</summary>
|
||||
|
||||
- [:simple-github: GitHub](https://github.com/photoprism)
|
||||
|
||||
</details>
|
||||
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
#### `downloads`
|
||||
|
||||
This is a special type of collapsible admonition, used to generate the download links section. It is only used within recommendation cards, as shown in the example above.
|
||||
|
||||
```markdown title="Downloads Section"
|
||||
<details class="downloads" markdown>
|
||||
<summary>Downloads</summary>
|
||||
|
||||
- [:simple-googleplay: Google Play](https://play.google.com/store/apps/details?id=ch.protonmail.android)
|
||||
- [:simple-appstore: App Store](https://apps.apple.com/app/id979659905)
|
||||
- [:simple-github: GitHub](https://github.com/ProtonMail/proton-mail-android/releases)
|
||||
- [:fontawesome-brands-windows: Windows](https://proton.me/mail/bridge#download)
|
||||
- [:simple-apple: macOS](https://proton.me/mail/bridge#download)
|
||||
- [:simple-linux: Linux](https://proton.me/mail/bridge#download)
|
||||
- [:octicons-browser-16: Web](https://mail.proton.me)
|
||||
|
||||
</details>
|
||||
```
|
||||
|
||||
<div class="result" markdown>
|
||||
|
||||
<details class="downloads" markdown>
|
||||
<summary>Downloads</summary>
|
||||
|
||||
- [:simple-googleplay: Google Play](https://play.google.com/store/apps/details?id=ch.protonmail.android)
|
||||
- [:simple-appstore: App Store](https://apps.apple.com/app/id979659905)
|
||||
- [:simple-github: GitHub](https://github.com/ProtonMail/proton-mail-android/releases)
|
||||
- [:fontawesome-brands-windows: Windows](https://proton.me/mail/bridge#download)
|
||||
- [:simple-apple: macOS](https://proton.me/mail/bridge#download)
|
||||
- [:simple-linux: Linux](https://proton.me/mail/bridge#download)
|
||||
- [:octicons-browser-16: Web](https://mail.proton.me)
|
||||
|
||||
</details>
|
||||
|
||||
</div>
|
||||
|
||||
## Old Format
|
||||
|
||||
Throughout the site, you may see some admonitions formatted similarly to these examples:
|
||||
|
||||
``` markdown title="Admonition"
|
||||
!!! note
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
||||
massa, nec semper lorem quam in massa.
|
||||
```
|
||||
|
||||
<div class="result" markdown>
|
||||
|
||||
<div class="admonition note" markdown>
|
||||
<p class="admonition-title">Note</p>
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
||||
massa, nec semper lorem quam in massa.
|
||||
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
``` markdown title="Collapsible Admonition"
|
||||
??? example "Custom Title"
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
||||
massa, nec semper lorem quam in massa.
|
||||
```
|
||||
|
||||
<div class="result" markdown>
|
||||
|
||||
<details class="example" markdown>
|
||||
<summary>Custom Title</summary>
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
|
||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
||||
massa, nec semper lorem quam in massa.
|
||||
|
||||
</details>
|
||||
|
||||
</div>
|
||||
|
||||
**This format is no longer used going forward,** because it is incompatible with newer versions of our translation software at Crowdin. When adding a new page to the site, only the newer HTML-based format should be used.
|
||||
|
||||
There is no rush to convert admonitions with the old format to the new format. Pages currently using this formatting should continue to work, but we will be updating them to use the newer HTML-based format above over time as we continue to update the site.
|
||||
@ -1,23 +0,0 @@
|
||||
---
|
||||
title: Branding Guidelines
|
||||
description: A guide for journalists and website contributors on proper branding of the Privacy Guides wordmark and logo.
|
||||
---
|
||||
|
||||
The name of the website is **Privacy Guides** and should **not** be changed to:
|
||||
|
||||
<div class="pg-red" markdown>
|
||||
- PrivacyGuides
|
||||
- Privacy guides
|
||||
- PG
|
||||
- PG.org
|
||||
</div>
|
||||
|
||||
The name of the Subreddit is **r/PrivacyGuides** or **the Privacy Guides Subreddit**.
|
||||
|
||||
Additional branding guidelines can be found at [github.com/privacyguides/brand](https://github.com/privacyguides/brand)
|
||||
|
||||
## Trademark
|
||||
|
||||
"Privacy Guides" and the shield logo are trademarks owned by Jonah Aragon, unlimited usage is granted to the Privacy Guides project.
|
||||
|
||||
Without waiving any of its rights, Privacy Guides does not advise others on the scope of its intellectual property rights. Privacy Guides does not permit or consent to any use of its trademarks in any manner that is likely to cause confusion by implying association with or sponsorship by Privacy Guides. If you are aware of any such use, please contact Jonah Aragon at `jonah@privacyguides.org`. Consult your legal counsel if you have questions.
|
||||
@ -1,78 +0,0 @@
|
||||
---
|
||||
title: Commit Messages
|
||||
description: A guide for website contributors on using useful Git commit messages when making website change requests.
|
||||
---
|
||||
|
||||
For our commit messages we follow the style provided by [Conventional Commits](https://conventionalcommits.org). Not all of those suggestions are appropriate for Privacy Guides, so the main ones we use are:
|
||||
|
||||
## Update to existing text
|
||||
|
||||
This example could be used for an item already on the site, but includes a minor update to the description.
|
||||
|
||||
```text
|
||||
update: Add mention of security audit (#0000)
|
||||
```
|
||||
|
||||
## Addition or removal of recommendations/pages
|
||||
|
||||
This example is for the addition or removal of an item. You may elaborate why it was removed in the commit paragraph below. Note the extra `!` to draw attention to a major change.
|
||||
|
||||
```text
|
||||
update!: Remove foobar (#0000)
|
||||
|
||||
Foobar was removed due to it having numerious security issues and being unmaintained.
|
||||
```
|
||||
|
||||
You can actually add a `!` to *any* of the types on this page to denote particularly large changes, but this is generally where it will be most appropriate.
|
||||
|
||||
## Feature/enhancement
|
||||
|
||||
For new features or enhancements to the site, e.g. things that have the `enhancements` label on GitHub, it may be appropriate to signify these with:
|
||||
|
||||
```text
|
||||
feat: Add blah blah (#0000)
|
||||
|
||||
This change adds the forum topics to the main page
|
||||
```
|
||||
|
||||
## Minor changes
|
||||
|
||||
Small changes that **don't affect the meaning** of the article, e.g. correcting a typo, fixing grammar, changing formatting/whitespace, CSS updates, etc.
|
||||
|
||||
```text
|
||||
style: Typo correction in VPN overview
|
||||
```
|
||||
|
||||
## Development-related types
|
||||
|
||||
These commit types are typically used for changes that won't be visible to the general audience.
|
||||
|
||||
We use `fix:` for changes that fix site related bugs. These things will usually have the `bug` label on GitHub.
|
||||
|
||||
```text
|
||||
fix: Remove broken Invidious embeds (#0000)
|
||||
```
|
||||
|
||||
We use `docs:` to denote changes to the developer documentation for this website, including (but not limited to) for example the README file, or most pages in `/docs/about` or `/docs/meta`:
|
||||
|
||||
```text
|
||||
docs: Update Git commit message guidelines (#0000)
|
||||
```
|
||||
|
||||
We use `build:` for commits related to our build process, mainly dependency updates.
|
||||
|
||||
```text
|
||||
build: Bump modules/mkdocs-material from 463e535 to 621a5b8
|
||||
```
|
||||
|
||||
We use `ci:` for commits related to GitHub Actions, DevContainers, or other automated build platforms.
|
||||
|
||||
```text
|
||||
ci: Update Netlify config (#0000)
|
||||
```
|
||||
|
||||
We use `refactor:` for changes which neither fix a bug nor add a feature, e.g. rearranging files, navigation order, etc.
|
||||
|
||||
```text
|
||||
refactor: Move docs/assets to theme/assets
|
||||
```
|
||||
@ -1,44 +0,0 @@
|
||||
---
|
||||
title: Git Recommendations
|
||||
description: A guide for website contributors on using Git effectively.
|
||||
---
|
||||
If you make changes to this website on GitHub.com's web editor directly, you shouldn't have to worry about this. If you are developing locally and/or are a long-term website editor (who should probably be developing locally!), consider these recommendations.
|
||||
|
||||
## Enable SSH Key Commit Signing
|
||||
|
||||
You can use an existing SSH key for signing, or [create a new one](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
|
||||
|
||||
1. Configure your Git client to sign commits and tags by default (remove `--global` to only sign by default for this repo):
|
||||
|
||||
```bash
|
||||
git config --global commit.gpgsign true
|
||||
git config --global gpg.format ssh
|
||||
git config --global tag.gpgSign true
|
||||
```
|
||||
|
||||
2. Set your SSH key for signing in Git with the following command, substituting `/PATH/TO/.SSH/KEY.PUB` with the path to the public key you'd like to use, e.g. `/home/user/.ssh/id_ed25519.pub`:
|
||||
|
||||
```bash
|
||||
git config --global user.signingkey /PATH/TO/.SSH/KEY.PUB
|
||||
```
|
||||
|
||||
Ensure you [add your SSH key to your GitHub account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account#adding-a-new-ssh-key-to-your-account) **as a Signing Key** (as opposed to or in addition to as an Authentication Key).
|
||||
|
||||
## Rebase on Git pull
|
||||
|
||||
Use `git pull --rebase` instead of `git pull` when pulling in changes from GitHub to your local machine. This way your local changes will always be "on top of" the latest changes on GitHub, and you avoid merge commits (which are disallowed in this repo).
|
||||
|
||||
You can set this to be the default behavior:
|
||||
|
||||
```bash
|
||||
git config --global pull.rebase true
|
||||
```
|
||||
|
||||
## Rebase from `main` before submitting a PR
|
||||
|
||||
If you are working on your own branch, run these commands before submitting a PR:
|
||||
|
||||
```bash
|
||||
git fetch origin
|
||||
git rebase origin/main
|
||||
```
|
||||
@ -1,43 +0,0 @@
|
||||
---
|
||||
title: Commenting on PRs
|
||||
description: A guide on participating in Pull Request discussions.
|
||||
---
|
||||
Please refrain from using the general **Add a comment** box in GitHub PRs when leaving a comment or performing a review.
|
||||
|
||||
|
||||
|
||||
Comments that are left like this are not *threaded*, which makes it difficult to keep track of multiple conversations.
|
||||
|
||||
Comments that are instead left in the manner described below will have a built-in reply box to keep conversations in a single thread. These comments can also be marked as resolved afterwards, so that discussion can be tracked more easily.
|
||||
|
||||
|
||||
|
||||
## Commenting
|
||||
|
||||
To start a threaded comment, you should leave all comments under the :octicons-file-diff-16: **Files changed** tab in a PR.
|
||||
|
||||
|
||||
|
||||
To leave a *general* comment on a PR, click the :octicons-comment-16: comment icon to the right of a file:
|
||||
|
||||
|
||||
|
||||
If the PR has multiple files changed, comment on the primary or most relevant file changed, or comment on the first file if you can't decide.
|
||||
|
||||
To leave a comment *on a specific line* of a PR, hover over the line where you'd like to add a comment, and click the blue comment icon:
|
||||
|
||||
|
||||
|
||||
(Optionally, you can add a comment on multiple lines. You can click the line number of the first line you want to comment on and drag down to select a range of lines, then click the blue comment icon on the last line you want to comment on. Alternatively, you can click the blue comment icon next to the first line you want to comment on, then drag down to the last line you want to comment on.)
|
||||
|
||||
Then, type your comment and click **Add single comment**.
|
||||
|
||||
## Reviewing
|
||||
|
||||
When performing a review, follow the same steps as above, but click **Start a review** (and subsequently, **Add a review comment**) instead of **Add single comment**.
|
||||
|
||||
Then, click the green **Finish your review** button at the top of the page.
|
||||
|
||||
Do not leave any discussion comments in the *Leave a comment* box in the review finalization pop-up. You can leave it blank, or leave a short note if it will not require any follow-up. To comment on something that will require further discussion, add a comment on a file as described above instead.
|
||||
|
||||
Then, click **Submit review**.
|
||||
@ -1,34 +0,0 @@
|
||||
---
|
||||
title: Translations
|
||||
description: A guide for website contributors on adding translations to our website.
|
||||
---
|
||||
|
||||
Crowdin has good documentation, and we suggest looking at their [Getting Started](https://support.crowdin.com/crowdin-intro) guide. Our site is largely written in [Markdown](https://en.wikipedia.org/wiki/Markdown), so it should be easy to contribute. This page contains some helpful pointers for translating some specific syntax you may encounter on our site.
|
||||
|
||||
Please join our localization room on Matrix ([#pg-i18n:aragon.sh](https://matrix.to/#/%23pg-i18n:aragon.sh)) if you have any additional questions, and read our [announcement blog post](https://blog.privacyguides.org/2023/02/26/i18n-announcement) for additional information about the project.
|
||||
|
||||
Note that the English version of the site is the primary version, meaning changes occur there first. If you notice a language falling behind the English version, please help out. We cannot guarantee the accuracy of all our translations. If you have a suggestion about content specific to your region, please open an issue or pull request to our [main repository](https://github.com/privacyguides/privacyguides.org).
|
||||
|
||||
## Translation output
|
||||
|
||||
Translation software gets the translation quite accurate; however, you need to make sure the translated string is correct.
|
||||
|
||||
For example:
|
||||
|
||||
```text
|
||||
{ align=right }
|
||||
```
|
||||
|
||||
We have sometimes found that the syntax for inserting an image like above was missing the ` on which one you think sounds best. When invalid strings are deleted, they are removed from the organization's [translation memory](https://support.crowdin.com/enterprise/translation-memory), meaning that when the source string is seen again, it won't suggest the incorrect translation.
|
||||
|
||||
## Punctuation
|
||||
|
||||
For examples like the above admonitions, quotation marks, e.g.: `" "` must be used to specify string text. MkDocs will not correctly interpret other symbols i.e., `「 」` or `« »`. Other punctuation marks are fine for marking regular quotations within the text otherwise.
|
||||
|
||||
## Fullwidth alternatives and Markdown syntax
|
||||
|
||||
CJK writing systems tend to use alternative "fullwidth" variants of common symbols. These are different characters and cannot be used for Markdown syntax.
|
||||
|
||||
- Links must use regular parenthesis i.e. `(` (Left Parenthesis U+0028) and `)` (Right Parenthesis U+0029) and not `（` (Fullwidth Left Parenthesis U+FF08) or `）` (Fullwidth Right Parenthesis U+FF09)
|
||||
- Indented quoted text must use `:` (Colon U+003A) and not `：` (Fullwidth Colon U+FF1A)
|
||||
- Pictures must use `!` (Exclamation Mark U+0021) and not `！` (Fullwidth Exclamation Mark U+FF01)
|
||||
@ -1,95 +0,0 @@
|
||||
---
|
||||
title: Uploading Images
|
||||
description: A guide for website contributors on uploading images in the proper format and location.
|
||||
---
|
||||
|
||||
If you make changes to this website that involve adding new images or replacing existing ones, here are a couple of general recommendations:
|
||||
|
||||
## Images
|
||||
|
||||
- We **prefer** SVG images, but if those do not exist we can use PNG images. Additionally, for cover images, we prefer that they are obtained from [Unsplash](https://unsplash.com) and are in the WebP format.
|
||||
|
||||
Company logos should be square if possible, and at least 200x200px if they are PNGs (non-vector images).
|
||||
|
||||
## Optimization
|
||||
|
||||
### PNG
|
||||
|
||||
Use the [OptiPNG](https://sourceforge.net/projects/optipng) tool to optimize PNG images:
|
||||
|
||||
```bash
|
||||
optipng -o7 file.png
|
||||
```
|
||||
|
||||
### SVG
|
||||
|
||||
#### Inkscape
|
||||
|
||||
[Scour](https://github.com/scour-project/scour) all SVG images.
|
||||
|
||||
In Inkscape:
|
||||
|
||||
1. File > Save As...
|
||||
2. Set type to: Optimized SVG (*.svg)
|
||||
|
||||
In the **Options** tab:
|
||||
|
||||
- **Number of significant digits for coordinates** > **5**
|
||||
- [x] Turn on **Shorten color values**
|
||||
- [x] Turn on **Convert CSS attributes to XML attributes**
|
||||
- [x] Turn on **Collapse groups**
|
||||
- [x] Turn on **Create groups for similar attributes**
|
||||
- [ ] Turn off **Keep editor data**
|
||||
- [ ] Turn off **Keep unreferenced definitions**
|
||||
- [x] Turn on **Work around renderer bugs**
|
||||
|
||||
In the **SVG Output** tab under **Document options**:
|
||||
|
||||
- [ ] Turn off **Remove the XML declaration**
|
||||
- [x] Turn on **Remove metadata**
|
||||
- [x] Turn on **Remove comments**
|
||||
- [x] Turn on **Embedded raster images**
|
||||
- [x] Turn on **Enable viewboxing**
|
||||
|
||||
In the **SVG Output** under **Pretty-printing**:
|
||||
|
||||
- [ ] Turn off **Format output with line-breaks and indentation**
|
||||
- **Indentation characters** > Select **Space**
|
||||
- **Depth of indentation** > **1**
|
||||
- [ ] Turn off **Strip the "xml:space" attribute from the root SVG element**
|
||||
|
||||
In the **IDs** tab:
|
||||
|
||||
- [x] Turn on **Remove unused IDs**
|
||||
- [ ] Turn off **Shorten IDs**
|
||||
- **Prefix shortened IDs with** > `leave blank`
|
||||
- [x] Turn on **Preserve manually created IDs not ending with digits**
|
||||
- **Preserve the following IDs** > `leave blank`
|
||||
- **Preserve IDs starting with** > `leave blank`
|
||||
|
||||
#### CLI
|
||||
|
||||
The same can be achieved with the [Scour](https://github.com/scour-project/scour) command:
|
||||
|
||||
```bash
|
||||
scour --set-precision=5 \
|
||||
--create-groups \
|
||||
--renderer-workaround \
|
||||
--remove-descriptive-elements \
|
||||
--enable-comment-stripping \
|
||||
--enable-viewboxing \
|
||||
--indent=space \
|
||||
--nindent=1 \
|
||||
--no-line-breaks \
|
||||
--enable-id-stripping \
|
||||
--protect-ids-noninkscape \
|
||||
input.svg output.svg
|
||||
```
|
||||
|
||||
### WebP
|
||||
|
||||
Use the [`cwebp`](https://developers.google.com/speed/webp/docs/using) command to convert PNG or JPEG image files to WebP format:
|
||||
|
||||
```bash
|
||||
cwebp -m 6 input_file -o output.webp
|
||||
```
|
||||
@ -1,88 +0,0 @@
|
||||
---
|
||||
title: Writing Style
|
||||
description: Our official writing style handbook for website contributors.
|
||||
---
|
||||
|
||||
Privacy Guides is written in American English, and you should refer to [APA Style guidelines](https://apastyle.apa.org/style-grammar-guidelines/grammar) when in doubt.
|
||||
|
||||
In general the [United States federal plain language guidelines](https://plainlanguage.gov/guidelines) provide a good overview of how to write clearly and concisely. We highlight a few important notes from these guidelines below.
|
||||
|
||||
## Writing for our audience
|
||||
|
||||
Privacy Guides' intended [audience](https://plainlanguage.gov/guidelines/audience) is primarily adults who use technology. Don't dumb down content as if you are addressing a middle-school class, but don't overuse complicated terminology about concepts average computer users wouldn't be familiar with.
|
||||
|
||||
### Address only what people want to know
|
||||
|
||||
People don't need overly complex articles with little relevance to them. Figure out what you want people to accomplish when writing an article, and only include those details.
|
||||
|
||||
> Tell your audience why the material is important to them. Say, “If you want a research grant, here’s what you have to do.” Or, “If you want to mine federal coal, here’s what you should know.” Or, “If you’re planning a trip to Rwanda, read this first.”
|
||||
|
||||
### Address people directly
|
||||
|
||||
We're writing *for* a wide variety of people, but we are writing *to* the person who is actually reading it. Use "you" to address the reader directly.
|
||||
|
||||
> More than any other single technique, using “you” pulls users into the information and makes it relevant to them.
|
||||
>
|
||||
> When you use “you” to address users, they are more likely to understand what their responsibility is.
|
||||
|
||||
Source: [plainlanguage.gov](https://plainlanguage.gov/guidelines/audience/address-the-user)
|
||||
|
||||
### Avoid "users"
|
||||
|
||||
Avoid calling people "users", in favor of "people", or a more specific description of the group of people you are writing for.
|
||||
|
||||
## Organizing content
|
||||
|
||||
Organization is key. Content should flow from most to least important information, and use headers as much as needed to logically separate different ideas.
|
||||
|
||||
- Limit the document to around five or six sections. Long documents should probably be broken up into separate pages.
|
||||
- Mark important ideas with **bold** or *italics*.
|
||||
|
||||
Source: [plainlanguage.gov](https://plainlanguage.gov/guidelines/design)
|
||||
|
||||
### Begin with a topic sentence
|
||||
|
||||
> If you tell your reader what they’re going to read about, they’re less likely to have to read your paragraph again. Headings help, but they’re not enough. Establish a context for your audience before you provide them with the details.
|
||||
>
|
||||
> We often write the way we think, putting our premises first and then our conclusion. It may be the natural way to develop thoughts, but we wind up with the topic sentence at the end of the paragraph. Move it up front and let users know where you’re going. Don’t make readers hold a lot of information in their heads before getting to the point.
|
||||
|
||||
Source: [plainlanguage.gov](https://plainlanguage.gov/guidelines/organize/have-a-topic-sentence)
|
||||
|
||||
## Choose your words carefully
|
||||
|
||||
> Words matter. They are the most basic building blocks of written and spoken communication. Don’t complicate things by using jargon, technical terms, or abbreviations that people won’t understand.
|
||||
|
||||
We should try to avoid abbreviations where possible, but technology is full of abbreviations. In general, spell out the abbreviation/acronym the first time it is used on a page, and add the abbreviation to the abbreviation glossary file when it is used repeatedly.
|
||||
|
||||
> Kathy McGinty offers tongue-in-cheek instructions for bulking up your simple, direct sentences:
|
||||
>
|
||||
> > There is no escaping the fact that it is considered very important to note that a number of various available applicable studies ipso facto have generally identified the fact that additional appropriate nocturnal employment could usually keep juvenile adolescents off thoroughfares during the night hours, including but not limited to the time prior to midnight on weeknights and/or 2 a.m. on weekends.
|
||||
>
|
||||
>And the original, using stronger, simpler words:
|
||||
>
|
||||
> > More night jobs would keep youths off the streets.
|
||||
|
||||
## Be concise
|
||||
|
||||
> Unnecessary words waste your audience’s time. Great writing is like a conversation. Omit information that the audience doesn’t need to know. This can be difficult as a subject-matter expert, so it’s important to have someone look at the information from the audience’s perspective.
|
||||
|
||||
Source: [plainlanguage.gov](https://plainlanguage.gov/guidelines/concise)
|
||||
|
||||
## Keep text conversational
|
||||
|
||||
> Verbs are the fuel of writing. They give your sentences power and direction. They enliven your writing and make it more interesting.
|
||||
>
|
||||
> Verbs tell your audience what to do. Make sure it’s clear who does what.
|
||||
|
||||
### Use active voice
|
||||
|
||||
> Active voice makes it clear who is supposed to do what. It eliminates ambiguity about responsibilities. Not “It must be done,” but “You must do it.”
|
||||
|
||||
Source: [plainlanguage.gov](https://plainlanguage.gov/guidelines/conversational/use-active-voice)
|
||||
|
||||
### Use "must" for requirements
|
||||
|
||||
> - “must” for an obligation
|
||||
> - “must not” for a prohibition
|
||||
> - “may” for a discretionary action
|
||||
> - “should” for a recommendation
|
||||
33
mkdocs.yml
33
mkdocs.yml
@ -449,32 +449,23 @@ nav:
|
||||
!ENV [NAV_FORUM_LINK, "https://discuss.privacyguides.net/"]
|
||||
- !ENV [NAV_ABOUT, "About"]:
|
||||
- "about.md"
|
||||
- "about/criteria.md"
|
||||
- "about/donate.md"
|
||||
- !ENV [NAV_ABOUT_TEAM_MEMBERS, "Team Members"]:
|
||||
https://discuss.privacyguides.net/u?group=team&order=solutions&period=all
|
||||
- !ENV [NAV_ABOUT_POLICIES, "Policies"]:
|
||||
- "about/criteria.md"
|
||||
- "about/donation-acceptance-policy.md"
|
||||
- "about/executive-policy.md"
|
||||
- !ENV [NAV_DOCUMENTATION, "Documentation"]:
|
||||
- !ENV [NAV_DOCUMENTATION_ALL, "All Documentation"]:
|
||||
https://discuss.privacyguides.net/c/documentation/9410
|
||||
- !ENV [NAV_DOCUMENTATION_POLICIES, "Policies"]:
|
||||
https://discuss.privacyguides.net/tags/c/documentation/9410/policy
|
||||
- !ENV [NAV_WRITING_GUIDE, "Writing Guide"]:
|
||||
https://discuss.privacyguides.net/tags/c/documentation/9410/writing
|
||||
- !ENV [NAV_TECHNICAL_GUIDES, "Technical Guides"]:
|
||||
https://discuss.privacyguides.net/tags/c/documentation/9410/technical
|
||||
- !ENV [NAV_ABOUT_MISC, "Miscellaneous"]:
|
||||
- "privacy.md"
|
||||
- "about/notices.md"
|
||||
- !ENV [NAV_COMMUNITY, "Community"]:
|
||||
- "about/statistics.md"
|
||||
- "about/jobs.md"
|
||||
- "about/contributors.md"
|
||||
- !ENV [NAV_ONLINE_SERVICES, "Online Services"]: "about/services.md"
|
||||
- !ENV [NAV_CODE_OF_CONDUCT, "Code of Conduct"]: "CODE_OF_CONDUCT.md"
|
||||
- "about/statistics.md"
|
||||
- !ENV [NAV_CONTRIBUTING, "Contributing"]:
|
||||
- !ENV [NAV_WRITING_GUIDE, "Writing Guide"]:
|
||||
- "meta/writing-style.md"
|
||||
- "meta/admonitions.md"
|
||||
- "meta/brand.md"
|
||||
- "meta/translations.md"
|
||||
- !ENV [NAV_TECHNICAL_GUIDES, "Technical Guides"]:
|
||||
- "meta/uploading-images.md"
|
||||
- "meta/git-recommendations.md"
|
||||
- "meta/commit-messages.md"
|
||||
- "meta/pr-comments.md"
|
||||
|
||||
validation:
|
||||
nav:
|
||||
|
||||
Reference in New Issue
Block a user