From 67d2880e6a1a0d149a3771ce1e4a8ad2a14221f0 Mon Sep 17 00:00:00 2001 From: Sarah Jamie Lewis Date: Tue, 7 Mar 2023 11:48:56 -0800 Subject: [PATCH] Stubs --- blog/2023-03-10-cwtch-documentation.md | 53 ++++++++++++++++++++++++++ docs/contribute/developing.md | 40 +++++++++++++++++-- docs/contribute/documentation.md | 42 ++++++++++++++++++++ docs/contribute/stickers.md | 10 +++++ docs/contribute/testing.md | 8 +++- docs/contribute/translate.md | 8 +++- 6 files changed, 156 insertions(+), 5 deletions(-) create mode 100644 blog/2023-03-10-cwtch-documentation.md create mode 100644 docs/contribute/documentation.md create mode 100644 docs/contribute/stickers.md diff --git a/blog/2023-03-10-cwtch-documentation.md b/blog/2023-03-10-cwtch-documentation.md new file mode 100644 index 00000000..1d2a1b6a --- /dev/null +++ b/blog/2023-03-10-cwtch-documentation.md @@ -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) + + + +## 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) + diff --git a/docs/contribute/developing.md b/docs/contribute/developing.md index ff41f0b9..3b10c69d 100644 --- a/docs/contribute/developing.md +++ b/docs/contribute/developing.md @@ -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) + +::: \ No newline at end of file diff --git a/docs/contribute/documentation.md b/docs/contribute/documentation.md new file mode 100644 index 00000000..673aff53 --- /dev/null +++ b/docs/contribute/documentation.md @@ -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**. + +::: \ No newline at end of file diff --git a/docs/contribute/stickers.md b/docs/contribute/stickers.md new file mode 100644 index 00000000..155368e1 --- /dev/null +++ b/docs/contribute/stickers.md @@ -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) + diff --git a/docs/contribute/testing.md b/docs/contribute/testing.md index 5f516ba6..b1431c4c 100644 --- a/docs/contribute/testing.md +++ b/docs/contribute/testing.md @@ -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. \ No newline at end of file +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) + +::: \ No newline at end of file diff --git a/docs/contribute/translate.md b/docs/contribute/translate.md index 54cee0d6..35fd6a8d 100644 --- a/docs/contribute/translate.md +++ b/docs/contribute/translate.md @@ -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. \ No newline at end of file +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) + +::: \ No newline at end of file