cwtch.im
/
docs.cwtch.im
4
0
Fork 3
Code Issues 2 Pull Requests Projects Releases Wiki Activity

Stubs

This commit is contained in:
Sarah Jamie Lewis 2023-03-07 11:48:56 -08:00
parent 14c914ac77
commit 67d2880e6a
6 changed files with 156 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
blog/2023-03-10-cwtch-documentation.md Normal file
View File

@ -0,0 +1,53 @@
---
title: Cwtch Documentation
description: ""
slug: cwtch-documentation
tags: [cwtch, cwtch-stable, documentation, security-handbook]
image: /img/devlog8_small.png
hide_table_of_contents: false
toc_max_heading_level: 4
authors:
- name: Sarah Jamie Lewis
title: Executive Director, Open Privacy Research Society
image_url: /img/sarah.jpg
---
One of the main streams of work in the lead up to Cwtch Stable has been improving all aspects of Cwtch Documentation. In this development log we will highlight some of the major updates over the last few weeks.
![](/img/devlog8.png)
<!--truncate-->
## Cwtch Secure Development Handbook
One of the earliest compendiums of Cwtch documentation was the Cwtch Secure Development Handbook. This handbook provided an overview of the various parts of the Cwtch ecosystem, the known risks, and any existing mitigations. The handbook was designed to serve as a guide to developers who were building or extending Cwtch, and over the years it also served as a permanent home for documenting long-standing design decisions.
We have [now ported the the handbook to this documentation site](/security/intro), along with updating some of the contents. Over the next few months we will be expanding this section to include new sections on fuzzing, plugins, and client implementation.
## Volunteer Development
We have noticed an uptick in the number of people reaching out interested in contributing to cwtch development. In order to help people get acclimated to our development flow we have created a new section on the main documentation site called [Developing Cwtch](/docs/contribute/developing) - there you will find a collection of useful links and information about how to get started with Cwtch development, what libraries and tools we use, how pull requests are validated and verified, and how to choose and issue to work on.
If you are interested in getting started with cwtch development then please check it out, and feel free to reach out to `team@cwtch.im` (or open a an issue) with any questions.
## Documentation Style Guide
This we we have also hit another core goal for the Cwtch Stable roadmap by [defining a styleguide for Cwtch Documentation](/docs/contribute/documentation). Over the coming weeks we will be improving existing documentation up to this standard.
## Next Steps
As these changes are made, and these goals met we will be posting about them here! Subscribe to our [RSS feed](/blog/rss.xml), [Atom feed](/blog/atom.xml), or [JSON feed](/blog/feed.json) to stay up to date, and get the latest on, all Cwtch development.
## Help us go further!
We couldn't do what we do without all the wonderful community support we get, from [one-off donations](https://openprivacy.ca/donate) to [recurring support via Patreon](https://www.patreon.com/openprivacy).
If you want to see us move faster on some of these goals and are in a position to, please [donate](https://openprivacy.ca/donate). If you happen to be at a company that wants to do more for the community and this aligns, please consider donating or sponsoring a developer.
Donations of **$5 or more** can opt to receive stickers as a thank-you gift!
For more information about donating to Open Privacy and claiming a thank you gift [please visit the Open Privacy Donate page](https://openprivacy.ca/donate/).
![A Photo of Cwtch Stickers](/img/stickers-new.jpg)

40
docs/contribute/developing.md
View File

@ -6,9 +6,43 @@ sidebar_position: 1
This section documents some ways to get started with Cwtch Development.
:::info
## Cwtch Issues Tracking Process
This documentation page is a stub. You can help
by [expanding it](https://git.openprivacy.ca/cwtch.im/docs.cwtch.im).
All Cwtch issues are tracked from the [cwtch-ui git repository](https://git.openprivacy.ca/cwtch.im/cwtch-ui/issues), even if the bug/feature originates in an upstream library. This allows us to keep everything in one place.
Issues are generally divided into 4 distinct categories:
- **Unprocessed** - These are new issues that have not been discussed by the Cwtch team.
- **Scheduled** - These issues have been planned for an upcoming release. They are usually tagged with the release they are expected to be fixed in e.g. `cwtch-1.11`. A core cwtch team member is likely working on the issue, or is expecting to work on the issue in the coming weeks.
- **Desired** - These are issues that we would like to fix but for some reason we are unable to schedule. This might be because the feature is large and requires a lot of effort, or because there is some blocker (e.g. a missing feature in Flutter or some other library) that prevents work on the feature.
- **Help Wanted** - These are generally small issues that we would like to fix but that have been designated low priority. These are ideal first issues for volunteers.
If you would like to work on an open bug/feature, please comment on the issue and a member of the Cwtch team will follow up with advice on where to go from there. This helps us keep track of who is working on what problems, and reduces the amount of duplicate work. We aim to answer most queries within 24 hours, feel free to "bump" an issue if it takes longer than that.
:::note
Due to an issue with our email provider, we are currently unable to consistently send email from our gitea instance. Please regularly check open issues / pull-requests for updates (or subscribe to the repositories rss feeds)
:::
## Cwtch Pull-Request Process
All pull-requests must be reviewed and approved by a core cwtch team member prior to merging. Sarah reviews all new and active pull requests multiple times a week.
### Build Bot
All Cwtch projects are set up with automated builds and testing. Every pull request is expected to be able to pass through these pipelines prior to being merged. If buildbot reports a failure then Sarah will work with you to determine the issue, and any necessary fixes.
Buildbot can fail for reasons beyond your control e.g. many of our integration tests rely setting up Tor connections, these can be brittle on occasion and result in timeouts and failures. Always confirm the root cause of a test failure before deciding what to do next.
## Useful Resources
- [Cwtch Ecosystem Overview](/security/components/ecosystem-overview) - a summary of active Cwtch repositories from the Cwtch Secure Development Handbook
:::note
All contributions are [eligible for stickers](/docs/contribute/stickers)
:::

42
docs/contribute/documentation.md Normal file
View File

@ -0,0 +1,42 @@
---
sidebar_position: 6
---
# Documentation Style Guide
This section documents the expected structure and quality of Cwtch documentation.
## Screenshots and Cast of Characters
Most Cwtch documentation should feature at least one screenshot or animated image. Screenshots of the Cwtch application should be focused on the feature being described by the documentation.
To ensure consistency between screenshots we suggest that the profile involved should serve particular, constant, roles.
- **Alice** - used to represent the primary profile.
- **Bob** - the primary contact, useful when demonstrating peer-to-peer features
- **Carol** - a secondary contact, useful when demonstrating group features
- **Mallory** - representing a malicious peer (to be used when demonstrating blocking functionality)
## Experiments
All features that rely on an experiment being enabled should all this out prominently at the top of the page e.g.:
:::caution Experiments Required
This feature requires [Experiments Enabled](https://docs.cwtch.im/docs/settings/introduction#experiments) and
the [Example Experiment](https://docs.cwtch.im/docs/settings/experiments/server-hosting) turned on.
:::
## Risks
If a feature might result in destruction of key material or permanent deletion of state, then these should also be called out
at the top of the documentation e.g.:
:::warning
This feature will result in **irreversible** deletion of key material. This **cannot be undone**.
:::

10
docs/contribute/stickers.md Normal file
View File

@ -0,0 +1,10 @@
---
sidebar_position: 10
---
# Stickers
All contributions are eligible for stickers. If you are contributing to bug, feature, testing, or language, or have contributed significantly in the past then please email erinn@openprivacy.ca with details and an address for us to mail stickers to.
![A Photo of Cwtch Stickers](/img/stickers-new.jpg)

8
docs/contribute/testing.md
View File

@ -30,4 +30,10 @@ Cwtch Nightly builds are development builds that contain new features that are r
The most recent few development versions of Cwtch are available from our [build server](https://build.openprivacy.ca/files/).
We **do not** recommend that testers always upgrade to the latest nightly, Instead, we will post a message to the Cwtch Release Candidate Testers group
when a significant nightly becomes available. A nightly is considered significant if it contains a new feature or a major bug fix.
when a significant nightly becomes available. A nightly is considered significant if it contains a new feature or a major bug fix.
:::note
All contributions are [eligible for stickers](/docs/contribute/stickers)
:::

8
docs/contribute/translate.md
View File

@ -16,4 +16,10 @@ The application is translated through [Lokalise](https://lokalise.com).
The handbook is translated through [Crowdin](https://crowdin.com).
1. Sign up for an account on the site.
2. Go to the [cwtch-users-handbook](https://crowdin.com/project/cwtch-users-handbook) project and join.
2. Go to the [cwtch-users-handbook](https://crowdin.com/project/cwtch-users-handbook) project and join.
:::note
All contributions are [eligible for stickers](/docs/contribute/stickers)
:::