Merge pull request #44 from biosafetylvl5/issue-documentation

Add documentation for related issues in release notes

.devcontainer/devcontainer.json

@@ -0,0 +1,22 @@
+// For format details, see https://aka.ms/devcontainer.json.
+// For config options, see the devcontainers
+// README at: https://github.com/devcontainers/templates/tree/main/src/python
+{
+	"name": "Python 3",
+	"image": "mcr.microsoft.com/devcontainers/python:1-3.12-bullseye",
+	"postCreateCommand": "pip3 install --user -e .",
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"lextudio.restructuredtext",
+				"ms-python.python",
+				"ms-python.flake8",
+				"tamasfe.even-better-toml",
+				"streetsidesoftware.code-spell-checker",
+				"ms-python.black-formatter",
+				"ms-azuretools.vscode-docker",
+				"ms-python.isort"
+			]
+		}
+	}
+}

pyproject.toml

@@ -32,6 +32,12 @@ doc = [
     "sphinx",                    # Required for building documentation, v7.2 errors
     "sphinxcontrib-runcmd",      # Required for running shell commands in documentation
     "sphinxcontrib-napoleon",    # Required for Google-style docstrings
+    "pinkrst", # for rst formatting
+    "black", # for rst formatting
+]
+
+test = [
+    "pytest", # for running tests
 ]
 
 [tool.poetry.scripts]

setup.py

@@ -20,5 +20,8 @@
         "platformdirs",
         "pydantic",
         "dateparser",
+        "pinkrst",
+        "black",
+        "pytest"
     ],
 )

sphinx/source/releases/latest/add-dev-container.yaml

@@ -0,0 +1,10 @@
+developer:
+- title: Add .devcontainer config file
+  description: Added devcontainer config file for developing brassy inside of a Docker
+    container using vscode.
+  files:
+    added:
+    - .devcontainer/devcontainer.json
+  date:
+    start: Nov 5 2024
+    finish: Nov 5 2024

sphinx/source/releases/latest/issue-documentation.yaml

@@ -0,0 +1,9 @@
+documentation:
+- title: Add documentation on issues
+  description: Added documentation on related issues for release notes. Also added
+    info on internal issues
+  files:
+    modified:
+    - sphinx/source/using-brassy.rst
+  related-issue:
+    internal: "Brassy#1 - Fake issue as an example for change"

sphinx/source/using-brassy.rst

@@ -181,6 +181,56 @@ Would output:
 
 .. literalinclude :: ./examples/basic-usage/new-release-note-header-footer
 
+Related Issue
+-------------
+
+Brassy can link issues (aka tasks, bugs, cards, etc.) to changes.
+
+For example:
+
+.. code-block:: yaml
+
+  continuous integration:
+  - title: 'Delete repo upon push'
+    description: 'I am done coding. Just delete the repo.'
+    files:
+      deleted:
+      - 'main.py'
+      added:
+      - 'delete-everything.py'
+    related-issue:
+      number: 999
+      repo_url: 'https://github.com/torvalds/linux'
+
+links the change "Delete repo upon push" to issue #999 on the linked linux repo.
+
+.. warning::
+
+  Issue information isn't rendered in generated release notes by default.
+  You must (currently) change your release generation template to include
+  issue info in your release notes.
+
+Support for Internal Repos
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some repositories aren't something you can share a link for.
+For example, they might be on an internal server or on your
+personal laptop.
+
+In these cases, you can specify issues without a URL. They must follow this pattern:
+
+.. code-block::
+
+  Repo Name Or Other String#999 - Description or other string
+
+For example:
+
+.. code-block:: yaml
+
+  related-issue:
+    internal: "Brassy#0 - Fake issue as an example for change"
+
+
 Change YAML directory
 ---------------------
 

src/brassy/templates/release_yaml_template.py

@@ -1,3 +1,4 @@
+from brassy.utils.settings_manager import get_settings
 import pathlib
 from typing import List, Optional, Dict, Union
 from datetime import date as Date
@@ -34,7 +35,8 @@ def check_at_least_one_field(self):
 
 
 class RelatedInternalIssue(BaseModel):
-    string: Optional[str] = Field(pattern=r"[A-Za-z]+#\d+ - .+", default=None)
+    internal: Optional[str] = Field(
+        pattern=r"[A-Za-z]+#\d+ - .+", default=None)
 
 
 class RelatedIssue(BaseModel):
@@ -98,8 +100,6 @@ class ReleaseNote(RootModel[Dict[str, List[ChangeItem]]]):
     pass
 
 
-from brassy.utils.settings_manager import get_settings
-
 Settings = get_settings("brassy")
 
 # List of categories stored in a variable