Add a command to add or update an entry for an issue. Update docs.

.github/workflows/validate.yml

@@ -16,4 +16,4 @@ jobs:
       with:
         cache: pip
     - run: pip install -r requirements.txt
-    - run: python ./validate-activities.py
+    - run: python ./activities.py validate

CONTRIBUTING.md

@@ -46,37 +46,7 @@ resources to it.
 
 ### Making a Position Request
 
-New specifications can be added by opening a new issue, or by making a pull request with the
-appropriate details in the `activities.json` file.
-
-If you decide to make a pull request, the `activities.py` script can help to fill in some of the
-relevant details:
-
-```
-    > ./activities.py add https://example.com/url_to_the_spec
-```
-
-If successful, it will modify `activities.json` with the new specification. Check the json file to make sure that the appropriate details are present:
-
-```
-{
-  "ciuName": "The short tagname from caniuse.com for the feature, if available",
-  "description": "A textual description; often, the spec's abstract",
-  "id": "A fragment identifier for the positions table",
-  "mdnUrl": "The URL of the MDN page documenting this specification or feature, if available",
-  "mozBugUrl": "The URL of the Mozilla bug tracking this specification, if available",
-  "mozPosition": "under consideration",
-  "mozPositionIssue": the number of the issue in this repo, if available,
-  "mozPositionDetail": "more information about Mozilla's position",
-  "org": one of ['IETF', 'W3C', 'WHATWG', 'Ecma', 'Unicode', 'Proposal', 'Other'],
-  "title": "The spec's title",
-  "url": "The canonical URL for the most recent version of the spec"
-}
-```
-`activities.json` is sorted by the title field. Once again, the `activities.py` script can help:
-```
-    > ./activities.py sort
-```
+New specifications can be added by opening a new issue.
 
 ### Asking Mozilla to Update a Position
 
@@ -118,7 +88,7 @@ reactions](https://github.com/blog/2119-add-reactions-to-pull-requests-issues-an
 issue or a specific comment.
 
 If you want to ask about (or contribute to) Firefox support for a specification, please use
-the respective Bugzilla bug, linked with a wrench 🔧 icon in the standards-position dashboard entry.
+the respective Bugzilla bug, linked in the standards-position dashboard entry / the GitHub issue.
 
 If an issue becomes overwhelmed by excessive advocacy or other off-topic comments,
 comments might be hidden, edited, or deleted, and the issue might be locked.
@@ -157,20 +127,41 @@ by giving appropriate context when filing issues, such as:
 to help evaluate what Mozilla thinks of it,
 and while doing that I noticed ..."
 
-Members of the Mozilla community are
-welcome to judge that we've come to sufficient consensus in the issue,
-and make a pull request to document that consensus by changing `activities.json`.
-When this happens, we'd like to try to keep the technical discussion
+#### Propose a position
+
+Add a comment in the issue with a summary of any concerns, a proposed position, and rationale (as appropriate).
+
+If you have [permission to add labels](https://github.com/orgs/mozilla/teams/standards-contributor), you can add "topic:", "concerns:", "venue:" labels. These will show up in the dashboard.
+
+The maintainers of this repo will add the appropriate "position:" label to the issue after 7 days if there's no disagreement, and then either close the issue or ask for a PR to add detailed rationale to the dashboard (see below).
+
+#### Add a rationale to the dashboard
+
+Some standards positions should have a recorded rationale in the dashboard. This is recorded in the `activities.yml` file.
+
+To add an item to `activities.yml` or to update the rationale of an existing item, run:
+
+```
+python3 activities.py add 1234 --rationale "..."
+```
+
+...where 1234 is the GitHub issue number. Optionally also add `--description "..."` to add a description of the feature or specification.
+
+Alternatively, edit `activities.yml` directly.
+
+Then submit a pull request with the changes.
+
+We'd like to try to keep the technical discussion
 about the position
 in the issue itself
 (so that it stays in one place),
 and limit the discussion in the pull request
-to the details of making the change to `activities.json`,
+to the details of making the change to `activities.yml`,
 and accurately communicating the consensus in the issue.
 
-Similarly, when changes to a proposal warrant an updated position and 
-there is sufficient consensus in subsequent comments on the issue, 
-make a pull request to document that updated consensus by changing `activities.json`.
+Similarly, when changes to a proposal warrant an updated position and
+there is sufficient consensus in subsequent comments on the issue,
+make a pull request to document that updated consensus by changing `activities.yml`.
 
 Tips:
 * Specification URLs should link to a living standard or editor’s draft if available.

validate-activities.py → activities.py

@@ -2,6 +2,7 @@
 import re
 import sys
 import argparse
+import requests
 from typing import Any, Dict, List, Tuple
 
 class YAMLValidator:
@@ -22,7 +23,7 @@ def load_yaml(self) -> Tuple[Dict[str, Any], Dict[int, str]]:
         except yaml.YAMLError as e:
             raise ValueError("Failed to load YAML: Invalid YAML format") from e
 
-    def log_error(self, message: str, key: str = "", line: int = None, fixable = False):
+    def log_error(self, message: str, key: str = "", line: int = None, fixable=False):
         tofix = " (Use --fix to fix.)" if fixable else ""
         if line is not None:
             self.errors.append(f"Error at line {line} in key '{key}': {message}{tofix}")
@@ -46,7 +47,7 @@ def validate_top_level_keys(self, data: Dict[str, Any], line_map: Dict[int, str]
                 data = dict(sorted(data.items()))
                 modified = True
             else:
-                self.log_error(f"Top-level keys must be in alphabetical order.", fixable = True)
+                self.log_error("Top-level keys must be in alphabetical order.", fixable=True)
 
         # Check for unique keys
         unique_keys = set(keys)
@@ -85,7 +86,7 @@ def validate_item(self, item: Dict[str, Any], key: str, line: int):
                         item.pop(legacy_key, None)
                         modified = True
                     else:
-                        self.log_error(f"Legacy key {legacy_key}. Please use GitHub issue labels instead.", key, line, fixable = True)
+                        self.log_error(f"Legacy key {legacy_key}. Please use GitHub issue labels instead.", key, line, fixable=True)
 
         # Optional fields validation
         if 'id' in item and (not isinstance(item['id'], str) or ' ' in item['id']):
@@ -142,13 +143,66 @@ def run(self):
                 self.save_fixes()
             # No success message on pass if not fixing
 
+    def add_issue(self, issue_num: int, description: str = None, rationale: str = None):
+        # Fetch issue data from GitHub
+        url = f"https://api.github.com/repos/mozilla/standards-positions/issues/{issue_num}"
+        response = requests.get(url)
+
+        if response.status_code != 200:
+            print(f"Failed to fetch issue {issue_num}: {response.status_code}")
+            sys.exit(1)
+
+        issue_data = response.json()
+        title = issue_data.get("title")
+
+        if not title:
+            print("No title found in the GitHub issue data.")
+            sys.exit(1)
+
+        # Load current YAML data
+        data, _ = self.load_yaml()
+
+        # Find if the issue already exists
+        issue_exists = False
+        for key, item in data.items():
+            if item.get('issue') == issue_num:
+                item['description'] = description if description is not None else item.get('description')
+                item['rationale'] = rationale if rationale is not None else item.get('rationale')
+                issue_exists = True
+                break
+
+        # Add new entry if the issue does not exist
+        if not issue_exists:
+            data[title] = {
+                "issue": issue_num,
+                "description": description,
+                "rationale": rationale
+            }
+
+        # Sort and save changes
+        data = dict(sorted(data.items()))
+        with open(self.file_path, 'w') as file:
+            yaml.dump(data, file, allow_unicode=True, default_flow_style=False)
+        print(f"Issue {issue_num} added or updated successfully.")
+
 if __name__ == "__main__":
-    parser = argparse.ArgumentParser(description="Validate and optionally fix activities.yml.")
+    parser = argparse.ArgumentParser(description="Manage activities.yml.")
+    parser.add_argument("command", choices=["validate", "add"], help="Specify 'validate' to validate or 'add' to add or update an item.")
+    parser.add_argument("issue_num", nargs="?", type=int, help="Issue number for the 'add' command.")
     parser.add_argument("--fix", action="store_true", help="Automatically fix issues (sort and drop legacy keys)")
+    parser.add_argument("--description", type=str, help="Set the description for the issue.")
+    parser.add_argument("--rationale", type=str, help="Set the rationale for the issue.")
     args = parser.parse_args()
 
-    validator = YAMLValidator("activities.yml", fix=args.fix)
-    try:
-        validator.run()
-    except ValueError as e:
-        print(f"Validation failed: {e}")
+    if args.command == "validate":
+        validator = YAMLValidator("activities.yml", fix=args.fix)
+        try:
+            validator.run()
+        except ValueError as e:
+            print(f"Validation failed: {e}")
+    elif args.command == "add":
+        if args.issue_num is None:
+            print("Please provide an issue number for 'add'.")
+            sys.exit(1)
+        validator = YAMLValidator("activities.yml")
+        validator.add_issue(args.issue_num, description=args.description, rationale=args.rationale)

pre-commit

@@ -45,7 +45,7 @@ exec 1>&2
 # Perform validation.
 trap 'git stash pop -q' EXIT
 git stash push -k -u -q -m "pre-commit stash from $(date '+%FT%T%z')"
-if ! "$python" validate-activities.py; then
+if ! "$python" activities.py validate; then
     echo "Validation failed; \`git commit --no-verify\` to suppress validation."
     exit 1
 fi

requirements.txt

@@ -1,4 +1,2 @@
-beautifulsoup4
 requests
-html5lib
 PyYAML