diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 0000000..dc42f77 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,23 @@ +name: Bug report +description: Report a reproducible problem in code, data processing or documentation. +title: '[Bug]: ' +body: + - type: textarea + id: problem + attributes: + label: Problem and expected behaviour + description: Explain the concrete trigger, actual result and expected result. + validations: + required: true + - type: textarea + id: reproduce + attributes: + label: Reproduction + description: Include commands, environment and commit or version. Use synthetic data. + validations: + required: true + - type: textarea + id: output + attributes: + label: Actual output + description: Include a minimal relevant excerpt with private information removed. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..64df7be --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Confidential security report + url: https://github.com/DirectGTM-Labs/.github/blob/main/SECURITY.md + about: Follow the private reporting instructions. Do not post secrets in public issues. + - name: Professional enquiries + url: https://mingmingcodes.com + about: See the maintainer's website and contact information. diff --git a/.github/ISSUE_TEMPLATE/evidence-correction.yml b/.github/ISSUE_TEMPLATE/evidence-correction.yml new file mode 100644 index 0000000..2ba5890 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/evidence-correction.yml @@ -0,0 +1,24 @@ +name: Evidence correction +description: Correct a definition, source, assumption, measurement or unsupported claim. +title: '[Evidence]: ' +body: + - type: input + id: affected + attributes: + label: Affected file or claim + validations: + required: true + - type: textarea + id: correction + attributes: + label: Proposed correction + description: Distinguish observation, inference and uncertainty. + validations: + required: true + - type: textarea + id: sources + attributes: + label: Evidence and sources + description: Prefer primary sources or reproducible observations. An LLM output alone is not evidence. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/feature-proposal.yml b/.github/ISSUE_TEMPLATE/feature-proposal.yml new file mode 100644 index 0000000..014ff9b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-proposal.yml @@ -0,0 +1,22 @@ +name: Feature proposal +description: Propose a focused improvement tied to an actual use case. +title: '[Proposal]: ' +body: + - type: textarea + id: use_case + attributes: + label: User and problem + description: Identify who benefits and the concrete problem they have. + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed change and acceptance criterion + description: Explain what success would look like and how it could be verified. + validations: + required: true + - type: textarea + id: tradeoffs + attributes: + label: Evidence, alternatives and limitations diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..3e046eb --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,20 @@ +## Problem and resulting behaviour + +Describe the concrete problem and what this change enables. + +## Verification + +List the checks actually run and their results. If something was not run, explain why. + +## Evidence and scope + +- Source or reproduction link, where relevant: +- Assistance level for a capability proof, where relevant: +- Remaining limitations or planned work: + +## Review checklist + +- [ ] The description distinguishes completed work from a proposal. +- [ ] Examples contain public, synthetic or suitably anonymised data. +- [ ] Private records, confidential information and credentials are excluded. +- [ ] Links and applicable licence terms have been reviewed. diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..8d1f04a --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,12 @@ +version: 2 +updates: + - package-ecosystem: github-actions + directory: / + schedule: + interval: weekly + open-pull-requests-limit: 2 + - package-ecosystem: pip + directory: /.github + schedule: + interval: weekly + open-pull-requests-limit: 1 diff --git a/.github/requirements-ci.txt b/.github/requirements-ci.txt new file mode 100644 index 0000000..f62ce0c --- /dev/null +++ b/.github/requirements-ci.txt @@ -0,0 +1 @@ +PyYAML==6.0.3 diff --git a/.github/scripts/check_content.py b/.github/scripts/check_content.py new file mode 100644 index 0000000..9d0564b --- /dev/null +++ b/.github/scripts/check_content.py @@ -0,0 +1,144 @@ +"""Check content changes; report existing scaffolding without claiming it works. + +This checks syntax and local file links, not source accuracy, schema semantics, +the quality of a growth method, or whether a Python application is implemented. +""" + +import argparse +import ast +import json +import os +from pathlib import Path +import re +import subprocess +import sys +import tomllib +from urllib.parse import unquote, urlsplit + +import yaml + + +TEXT_SUFFIXES = {'.md', '.json', '.yaml', '.yml', '.toml', '.py', '.sql', '.j2', '.psv'} +INLINE_LINK = re.compile(r'!?\[[^\]\n]*\]\(\s*(<[^>\n]+>|[^\s)]+)(?:\s+[\"\'][^\n]*?[\"\'])?\s*\)') + + +def git(root, *args): + return subprocess.check_output(['git', '-C', str(root), *args]) + + +def inspect_file(root, name): + path = root / name + issues = [] + if any(part != part.strip() for part in Path(name).parts): + issues.append('file or directory name has leading/trailing whitespace') + if path.suffix.lower() not in TEXT_SUFFIXES: + return issues + try: + text = path.read_text(encoding='utf-8') + if not text.strip(): + if path.name != '__init__.py': + issues.append('empty placeholder; not a completed implementation') + return issues + if path.suffix == '.json': + json.loads(text) + elif path.suffix in {'.yaml', '.yml'}: + yaml.safe_load(text) + elif path.suffix == '.toml': + tomllib.loads(text) + elif path.suffix == '.py': + ast.parse(text, filename=name) + elif path.suffix == '.md': + # Avoid links in fenced examples. Check inline local file links only; + # external URLs, reference-style links and section anchors are not checked. + in_fence = False + fence_mark = None + prose = [] + for line in text.splitlines(): + match = re.match(r'^\s*(`{3,}|~{3,})', line) + if match: + mark = match.group(1)[0] + if not in_fence: + in_fence, fence_mark = True, mark + elif mark == fence_mark: + in_fence, fence_mark = False, None + continue + if not in_fence: + prose.append(line) + for match in INLINE_LINK.finditer('\n'.join(prose)): + target = match.group(1).strip('<>') + parts = urlsplit(target) + if parts.scheme or parts.netloc or not parts.path: + continue + # Root-relative links on GitHub can be site routes, not repo files. + if parts.path.startswith('/'): + continue + destination = path.parent / unquote(parts.path) + if not destination.exists(): + issues.append('missing local link target: ' + target) + except (UnicodeError, ValueError, SyntaxError, yaml.YAMLError) as exc: + issues.append(str(exc)) + return issues + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--root', default='.') + parser.add_argument('--base', default=os.environ.get('BASE_SHA', '')) + parser.add_argument('--org-profile', action='store_true') + args = parser.parse_args() + root = Path(args.root).resolve() + tracked = git(root, 'ls-files', '-z').decode().split('\0')[:-1] + tracked = [name for name in tracked if (root / name).is_file()] + + required = ['README.md'] + is_profile = args.org_profile or os.environ.get('GITHUB_REPOSITORY', '').endswith('/.github') + if is_profile: + required.append('profile/README.md') + failures = [] + for name in required: + path = root / name + if not path.is_file() or not path.read_text(encoding='utf-8').strip(): + failures.append(name + ': required published entry point is missing or empty') + elif not re.search(r'^#\s+\S', path.read_text(encoding='utf-8'), re.MULTILINE): + failures.append(name + ': add a top-level Markdown title') + + base = args.base.strip() + if base and set(base) != {'0'}: + if not re.fullmatch(r'[0-9a-fA-F]{40,64}', base): + raise SystemExit('BASE_SHA must be a commit hash') + changed = set(git(root, 'diff', '--diff-filter=ACMR', '--name-only', '-z', base, 'HEAD').decode().split('\0')) + changed.discard('') + else: + changed = set() + print('Baseline/manual run: report existing scaffolding; required README entry points remain enforced.') + + backlog = [] + for name in tracked: + issues = inspect_file(root, name) + if issues: + entries = [name + ': ' + issue for issue in issues] + for issue, entry in zip(issues, entries): + # Planned scaffold files can remain empty or be moved. Only + # published README entry points must be nonempty at this stage. + if issue.startswith('empty placeholder') and name not in required: + backlog.append(entry) + elif name in changed or name in required: + failures.append(entry) + else: + backlog.append(entry) + if backlog: + print(f'Existing content backlog: {len(backlog)} issue(s). These are not functional-test passes.') + for item in backlog[:12]: + print('BACKLOG: ' + item) + if len(backlog) > 12: + print(f'... {len(backlog) - 12} more issue(s); run the script after each content update.') + if failures: + for item in failures: + print('FAIL: ' + item, file=sys.stderr) + return 1 + print(f'Content checks passed: {len(changed)} changed path(s); published entry points verified.') + return 0 + + +if __name__ == '__main__': + raise SystemExit(main()) diff --git a/.github/workflows/content-checks.yml b/.github/workflows/content-checks.yml new file mode 100644 index 0000000..6301da6 --- /dev/null +++ b/.github/workflows/content-checks.yml @@ -0,0 +1,37 @@ +name: Content CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: content-ci-${{ github.ref }} + cancel-in-progress: true + +jobs: + content-checks: + name: Content checks + runs-on: ubuntu-24.04 + timeout-minutes: 5 + steps: + - name: Check out repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + persist-credentials: false + - name: Set up Python + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: '3.12' + - name: Install CI dependencies + run: python -m pip install -r .github/requirements-ci.txt + - name: Check published entry points and changed content + env: + BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }} + run: python .github/scripts/check_content.py