First Blog Draft

.gitignore

@@ -20,3 +20,7 @@ yarn-debug.log*
 yarn-error.log*
 
 .idea
+.yarn
+.pnp.cjs
+.pnp.loader.mjs
+yarn.lock

blog/2023-01-06-path-to-cwtch-stable.md

@@ -0,0 +1,72 @@
+---
+title: Path to Cwtch Stable
+description: This is my first post on Docusaurus 2.
+slug: path-to-cwtch-stable
+tags: [cwtch, cwtch-stable]
+image_url: /img/1.10.midnight.png
+hide_table_of_contents: false
+authors:
+- name: Sarah Jamie Lewis
+  title: Executive Director, Open Privacy Research Society
+  url: https://openprivacy.ca/people/sarah-jamie-lewis/
+  image_url: https://openprivacy.ca/images/board/sarah.jpg
+---
+
+As of December 2022 we have released 10 versions of Cwtch Beta since the initial launch 18 months ago in June 2021.
+
+There is a consensus among the team that the next large step for the Cwtch project to take is a move from public **Beta** to **Stable** – marking a point at which we consider Cwtch to be secure, and usable.
+
+The post outlines the general principles that are guiding the development of Cwtch Stable, the obstacles that prevent a stable Cwtch release, and closes with an overview the next steps and a timeline to tackle them.
+
+![](/img/devlog1.png)
+
+<!--truncate-->
+
+### Tenets of Cwtch Stable
+
+It is important to state that Cwtch Stable **does not mean an end to Cwtch Development**, it instead establishes a baseline at which point Cwtch is considered to be a fully supported project. The Cwtch Team have set the following tenets that guide our decision-making and priorities:
+
+1. **Consistent Interface** – each new Cwtch release should be accompanied by consistent releases to all support libraries. This requires a stable and documents API so that we can be clear when upgrading a library will result in breaking change for downstream projects.  We should not, as a general rule, have to make breaking changes to this API interface in order to support new experimental features.
+2. **Universal Availability and Cohesive Support** –  people who use Cwtch understand that if Cwtch is available for a platform then that means all features will work as expected, that there are no surprise limitations, and any differences are well documented. People should not have to go out of their way to install Cwtch.
+3. **Reproducible Builds** – Cwtch builds should be trivially reproducible, including the ability to reproduce all bundled assets. Reproducibility should not rely on containerization, but all containers used in our build process should be reproducible.
+4. **Proven Security** – we can demonstrate that Cwtch provides first class security through well documented design, testing, and audit procedures. We should be able to do this for Cwtch in addition to all functional dependencies.
+
+### Known Problems
+
+1. **Lack of a Stable API for future feature development** – while the core Cwtch API has remained fairly unchanged in recent releases we understand that the addition of new features e.g. cohesive group support likely requires new API hooks that allow safe manipulation of Cwtch Peer state (transactional semantics and post-event hooks). Before we can even consider a stable release we need to define what this API should look like, and implement it. (Tenet 1)
+2. **Special functionality in libCwtch-go** – our C-API bridge (libCwtch-go) currently implements a lot of special functionality in support for both experimental features (e.g. profile images) and UI settings. This special behaviour makes it difficult to track feature responsibility. This behaviour must either be pushed back into the main Cwtch library, or defined to be application specific. (Tenet 1)
+3. **libCwtch-rs partial support**  - we currently do not officially consider libCwtch-rs when updating libCwtch-go as part of our release schedule, before we can consider a Cwtch Stable change we should have multiple releases where libCwtch-rs has full support for any and all new Cwtch features. (Tenet 1, Tenet 2)
+4. **Lack of Reproducible Pipelines** - while the vast majority of our build pipeline is automated, containerized, and reproducible; there remain assets that cannot be trivially constructed (e.g. Tor binaries) and builds that have non-reproducible elements (e.g. build-time injected via git tags, and go binaries including build user information). (Tenet 3)
+5. **Lack of up to date, and translated, Security Documentatio**n – the Cwtch security handbook is currently isolated from the rest of our documentation and doesn’t benefit from cross-linking, or translations. ( Tenet 4)
+6. **No Automated UI Tests** – we put a lot of work into building out a testing framework for the UI, but it currently sits mostly unused, and unexercised in our build pipelines. We should revisit that work. ( Tenet 4)
+7. **Code Signing Provider** – our previous code signing certificate provider had support issues, and we have not yet decided on a replacement ( Tenet 4)
+8. **Second-class Android Support**  - while we have put a lot of effort behind Android support across the Beta timeline, it is still clearly suffers from additional issues that desktops do not. In order to consider Cwtch stable we must resolve all existing Android bugs ( Tenet 2)
+9. **Lack of Fuzzing** – while Fuzzbot sets a standard high above most other secure communication applications, we can and should do better. Fuzzbot currently only targets user-endpoint messages, which are the most likely to result in real-world risk, but we should have the same coverage for internal events at both the network level, the Cwtch peer app message level, and the event bus level. (Tenet 4)
+10. **Lack of Formal Release Acceptance Process** – currently the features and experiments that get included in each release are determined in an ad-hoc consensus, this occasionally means that some features are left unsupported on certain platforms, and rarely bugs occur in platforms (Android in particular) due to “unrelated” changes. In order for Cwtch to be declared stable, a formal acceptance process must ensure that new changes do not break existing features., and that they work across all platforms. (Tenet2, Tenet 4)
+11. **Inconsistent Cwtch Information Discovery** – our current documentation is split between docs.cwtch.im, cwtch.im and docs.openprivacy.ca, in additional to blogs on Discreet Log. This makes it difficult for people to learn about Cwtch, and also means that our own explanations often must link across multiple different sites.
+12. **Incomplete Documentation** – docs.cwtch.im was very well received, however it still suffers from incomplete sections, missing links, and an overall lack of screenshots. What screenshots there are lack consistency in sizing, style, and feel.
+
+### Plan of Action
+
+Outside of the problems that have standalone solutions (e.g. find a new code signing provider, or fix all Android issues), there are a number of higher level activities that need to be complete before we can be confident in a Cwtch Stable release
+
+1. **Define, Publish, and Implement a Cwtch Interface Specification Documentation** – this should include examples of how new behaviour might be implemented from finer-grained composition. Must include moving all special functionality out of libCwtch-go. Should be followed up by implementing the proposed design. ( Tenet 1, Tenet 4)
+2. **Define, Publish, and Implement a Cwtch Release Process** – this document should outline the criteria for publishing a new release, the difference between major and minor versions, how features are tested, how regressions are caught before release, and who is responsible for different parts of the process ( Tenet 2)
+3. **Define, Publish, and Implement a Cwtch Support Document**  - including answers to the questions: what systems do we support, how do we decide what systems are supported, how do we handle new OS versions, and how does application support differ from library support ( Tenet 2)
+4. **Define, Publish, and Implement a Cwtch Packaging Document**  - as a supplement to the Support document we need to define what packaging we support, in addition to what app stores and managers we provide official releases for ( Tenet 2)
+5. **Define, Publish, and Implement a Reproducible Builds Document** – this should cover not only Cwtch binaries, but also Docker Containers, and included assets (e.g. Tor binaries). Followed up by implementing the plan into our build pipeline ( Tenet 3)
+6. **Expand the Cwtch Documentation Site** – to include the Security Handbook, development blogs, design documentation, and support plans. This should be our only publishing platform, outside of a landing page, and downloads on cwtch.im. This expansion should include a style guide for documentation and screenshots to ensure that we maintain consistent language and visualize when talking about a feature (e.g. we should use the same profile image style, theme, profile names etc.) ( Tenet 1, Tenet 2, Tenet 3, Tenet 4,)
+7. **Expand our Automated Testing to include UI and Fuzzing**  - integrate UI automated tests into our build pipeline. Expand our fuzzing to include the Event Bus, and PeerApp packets. Finally schedule work to integrate automated fuzzing into the build pipeline, so that all new features are fuzzed to the same level ( Tenet 4)
+8. **Re-evaluate all Issues across all Cwtch related repositories** – issues are either bugs that need to be fixed before stable (i.e. they are in service of one of the Tenets), new feature ideas that should be scheduled around stable work (i.e. they don’t align with a specific Tenets) or support requests for systems that need input from the Support and Packaging Plans.
+9. **Define a Stable Feature Set** – there are still a few features which do not exist in Cwtch Beta which would be required for a stable release e.g. Chat Search. Following on from the Cwtch Interface Specification Document the team should meet to decide what features Cwtch Stable will target, and these features should be prioritized for inclusion in Cwtch 1.11, Cwtch 1.12 and any future Beta releases.
+
+### Goals and Timelines
+
+1. By **1st February 2023**, the Cwtch team will have reviewed all existing Cwtch issues in line with this document, and established a timeline for including them in upcoming releases (or specifically commit to not including them in upcoming releases).
+2. By **1st February 2023**, the Cwtch team will have finalized a feature set that defines Cwtch Stable and established a timeline for including these features in upcoming Cwtch Beta releases.
+3. By **1st February 2023**, the Cwtch team will have expanded the Cwtch Documentation website to include a section for Security, Design Documents, Infrastructure and Support, in addition to a new development blog.
+4. By **31st March 2023**, the Cwtch team will have created a style guide for documentation and have used ensure that all Cwtch features have a consistent documentation available, with at least one screenshot (where applicable).
+5. By **31st March 2023** the Cwtch team will have published a Cwtch Interface Specification Document,  a Cwtch Release Process Document, a Cwtch Support Plan document, a Cwtch Packaging Document, and a document describing the Reproducible Builds Process. These documents will be available on a newly expanded Cwtch Documentation website.
+6. By **31st March 2023** the Cwtch team will have integrated automated UI tests into the build pipeline for the cwtch-ui repository
+7. By **31st March 2023** the Cwtch team will have integrated automated fuzzing into the build pipeline for all cwtch dependencies maintained by the Cwtch team.
+8. By **31st March 2023** the Cwtch team will have committed to a date, timeline, and roadmap for launching Cwtch Stable.

docs/profiles/create-a-profile.md

@@ -16,6 +16,6 @@ sidebar_position: 1.5
 
 Profiles are stored locally on disk and encrypted using a key derived from user-known password (via pbkdf2).
 
-Note that once encrypted, and stored on disk, the only way to recover a profile is by rederiving the password - as such it isn't possible to provide a full list of profiles a user might have access to until they enter a password.
+Note that, once encrypted and stored on disk, the only way to recover a profile is by rederiving the key from the password - as such it isn't possible to provide a full list of profiles a user might have access to until they enter a password.
 
 See also: [Cwtch Security Handbook: Profile Encryption & Storage](https://docs.openprivacy.ca/cwtch-security-handbook/profile_encryption_and_storage.html)

docusaurus.config.js

@@ -41,6 +41,12 @@ const config = {
           editUrl:
             'https://git.openprivacy.ca/cwtch.im/docs.cwtch.im/src/branch/main/',
         },
+        blog: {
+          // Please change this to your repo.
+          // Remove this to remove the "edit this page" links.
+          editUrl:
+              'https://git.openprivacy.ca/cwtch.im/docs.cwtch.im/src/branch/main/',
+        },
         theme: {
           customCss: require.resolve('./src/css/custom.css'),
         },
@@ -68,6 +74,11 @@ const config = {
             position: 'left',
             label: 'Cwtch Intro',
           },
+          {
+            to: 'blog',
+            position: 'left',
+            label: 'Development Log',
+          },
           {
             href: 'https://git.openprivacy.ca/cwtch.im',
             label: 'Git',
@@ -80,7 +91,6 @@ const config = {
         ],
       },
       footer: {
-        style: 'dark',
         links: [
           {
             title: 'Docs',
@@ -94,6 +104,10 @@ const config = {
           {
             title: 'Community',
             items: [
+              {
+                label: 'Mastodon',
+                href: 'https://fosstodon.org/@cwtch',
+              },
               {
                 label: 'Twitter',
                 href: 'https://twitter.com/cwtch_im',

src/css/custom.css

@@ -6,9 +6,10 @@
 
 :root {
   --ifm-color-primary: #8E64A5;
-  --ifm-font-color-base: #350052;
+  --ifm-font-color-base: #281831;
   --ifm-navbar-background-color: #FDF3FC;
   --ifm-code-font-size: 95%;
+  --ifm-footer-background-color: #FDF3FC;
   --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
 }
 
@@ -33,6 +34,7 @@
   --ifm-color-primary: #DFB9DE;
   --ifm-font-color-base: #FDF3FC;
   --ifm-navbar-background-color: #281831;
+  --ifm-footer-background-color: #281831;
   --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
 }