More docs (#8)

Signed-off-by: Oliver Tale-Yazdi <[email protected]>

README.md

@@ -18,21 +18,17 @@ This repo contains a [JSON schema](./releases-v1.schema.json) as schema for the
 |   stable2407-3 | ~2024-10-07 | ~2024-10-10 |  | Planned |
 |   stable2407-4 | ~2024-11-04 | ~2024-11-07 |  | Planned |
 |   stable2407-5 | ~2024-12-02 | ~2024-12-05 |  | Planned |
-|   stable2407-6 | ~2025-01-06 | ~2025-01-09 |  | Planned |
-|   (4 more) |  |  | | |
-| **stable2409** |   2024-09-02 | ~2024-09-25 | ~2025-09-25 | Testing |
+|   (5 more) |  |  | | |
+| **stable2409** |   2024-09-02 | ~2024-09-25 | ~2025-09-25 | Staging |
 |   stable2409-1 | ~2024-10-14 | ~2024-10-17 |  | Planned |
 |   stable2409-2 | ~2024-11-11 | ~2024-11-14 |  | Planned |
 |   stable2409-3 | ~2024-12-09 | ~2024-12-12 |  | Planned |
-|   stable2409-4 | ~2025-01-13 | ~2025-01-16 |  | Planned |
-|   (9 more) |  |  | | |
+|   (10 more) |  |  | | |
 | **stable2412** | ~2024-11-06 | ~2024-12-16 | ~2025-12-16 | Planned |
 |   stable2412-1 | ~2025-01-20 | ~2025-01-23 |  | Planned |
 |   stable2412-2 | ~2025-02-17 | ~2025-02-20 |  | Planned |
 |   stable2412-3 | ~2025-03-17 | ~2025-03-20 |  | Planned |
-|   stable2412-4 | ~2025-04-21 | ~2025-04-24 |  | Planned |
-|   (8 more) |  |  | | |
-
+|   (9 more) |  |  | | |
 
 <!-- TEMPLATE END -->
 
@@ -52,17 +48,28 @@ Subscribe to the calendar by adding this iCal link to your Google or Apple calen
 :-------------------------:|:-------------------------:
 ![](.assets/screenshot-google-cal.png)  |  ![](.assets/screenshot-apple-cal.png)
 
-## Cadency
+## Schedule
+
+### Releases
 
-The Polkadot SDK has a `stableYYMMDD` release every 3 months. Each stable release is supported for one year through a monthly patching schedule.  
-As there can be four stable releases in parallel, the patching schedule is aligned with the weeks of a month. Each stable release is assigned a week in which on Monday its patch will be cut off and on Thursday it will be published.
+The Polkadot SDK has a `stableYYMMDD` release every 3 months. Each stable release is supported for one year through a monthly patching schedule. The releases are not *exactly* 3 months apart, but we try to keep it close. The exact dates are in the calendar.  
+Stable releases undergo a 1.5 month QA period before being published. This explains the difference between the `cutoff` and `published` dates.
+
+### Patches
+
+The patching schedule of each stable release is assigned a week of the month. This works well, since there can be at most four stable releases maintained at once.  For example: release `stable2407` is always patched in the first week of a month. This means that on the first Monday of each month, a new patch is cut off, and on the first Thursday after that Monday, it is published.
 
 ![Monthly Patching](./.assets/monthly-patching.png)
 
-Stable releases undergo a 1.5 month QA period before being published. This explains the difference between the `cutoff` and `published` dates below.
+## Goals
+
+The two main goals of this repo are to improve:
+- **Communication**: clear information about past and upcoming releases. Hoarding information inside Parity is not helpful. This repo aims to make it easier for the Polkadot Ecosystem to know what's going on. This can be helpful to all departments; developers, marketing, devops, security etc.
+- **Expectations**: set clear expectations by having a public schedule. Know when what is coming.
 
 ## Maintenance
 
+
 ### Release Planning
 (how to add a new release to the json)
 

releases-v1.ics

@@ -166,14 +166,14 @@ BEGIN:VEVENT
 SUMMARY:stable2409 Cutoff
 DTSTART;VALUE=DATE:20240902
 DTEND;VALUE=DATE:20240903
-DESCRIPTION:Cutoff for stable2409 (testing)\n\nFull Calendar: https://gith
+DESCRIPTION:Cutoff for stable2409 (staging)\n\nFull Calendar: https://gith
  ub.com/paritytech/release-registry?tab=readme-ov-file#calendar
 END:VEVENT
 BEGIN:VEVENT
 SUMMARY:stable2409 Release
 DTSTART;VALUE=DATE:20240925
 DTEND;VALUE=DATE:20240926
-DESCRIPTION:Release of stable2409 (testing)\n\nFull Calendar: https://gith
+DESCRIPTION:Release of stable2409 (staging)\n\nFull Calendar: https://gith
  ub.com/paritytech/release-registry?tab=readme-ov-file#calendar
 END:VEVENT
 BEGIN:VEVENT

releases-v1.json

@@ -117,7 +117,7 @@
       },
       {
         "name": "stable2409",
-        "state": "testing",
+        "state": "staging",
         "cutoff": "2024-09-02",
         "publish": {
           "estimated": "2024-09-25"
@@ -396,4 +396,4 @@
     ],
     "changelog": "https://github.com/paritytech/polkadot-sdk/releases/tag/$TAG"
   }
-}
+}

releases-v1.schema.json

@@ -186,7 +186,7 @@
 					"type": "string",
 					"enum": [
 						"planned",
-						"testing",
+						"staging",
 						"released"
 					]
 				},

update-readme.py

@@ -69,7 +69,7 @@ def generate_markdown_table(data: Dict[str, Any]) -> str:
             is_patch_planned = isinstance(patch['state'], str) and patch['state'].lower() == 'planned'
             if is_patch_planned:
                 future_patches += 1
-            if future_patches < 5:
+            if future_patches < 4:
                 table += generate_row(patch, is_patch=True, is_recommended=is_recommended_patch, is_planned=is_patch_planned) + '\n'
             else:
                 table += f"| &nbsp;&nbsp;({len(patches) - i} more) |  |  | | |\n"
@@ -83,7 +83,7 @@ def update_readme(markdown_table: str) -> None:
             content = file.read()
             updated_content = re.sub(
                 r'(<!-- TEMPLATE BEGIN -->).*?(<!-- TEMPLATE END -->)',
-                r'\1\n\n' + markdown_table + r'\n\n\2',
+                r'\1\n\n' + markdown_table + r'\n\2',
                 content,
                 flags=re.DOTALL
             )