विकास मार्गदर्शिका

सेटअप

# क्लोन करें और dev डिपेंडेंसीज़ इंस्टॉल करें
git clone https://github.com/f5-sales-demo/api-specs.git
cd api-specs
make dev-install

# Spectral CLI इंस्टॉल करें (लिंटिंग स्टेज के लिए आवश्यक)
npm install -g @stoplight/spectral-cli

make dev-install .venv/ में एक virtualenv बनाता है और dev extras (pytest, ruff, mypy) के साथ प्रोजेक्ट इंस्टॉल करता है।

एनवायरनमेंट वेरिएबल्स

लाइव API सत्यापन के लिए आवश्यक:

export F5XC_API_URL="https://example-tenant.console.ves.volterra.io"
export F5XC_API_TOKEN="your-api-token"

इनके बिना, make validate ड्राई-रन मोड में फॉलबैक करता है।

पाइपलाइन चलाना

पूर्ण पाइपलाइन

make all
# चलाता है: download → validate → spectral-lint → reconcile → spectral-gate → release

व्यक्तिगत स्टेज

make download        # अपस्ट्रीम स्पेक्स प्राप्त करें
make validate        # लाइव API परीक्षण चलाएं (API टोकन आवश्यक)
make validate-dry    # ड्राई रन (कोई API कॉल नहीं)
make spectral-lint   # मूल स्पेक्स पर Spectral डिस्कवर मोड
make reconcile       # दोनों रिपोर्ट्स से फिक्स लागू करें
make spectral-gate   # रीकॉन्साइल्ड स्पेक्स पर Spectral क्वालिटी गेट
make release         # रिलीज़ पैकेज बनाएं

डॉक्यूमेंटेशन

make docs-generate   # रिपोर्ट्स से docs/01-validation-report.mdx पुनः जनरेट करें
make docs            # पूर्ण डॉक्यूमेंटेशन साइट बनाएं
make docs-serve      # हॉट रीलोड के साथ लोकल dev सर्वर

परीक्षण चलाना

make test           # कवरेज के साथ pytest
make lint           # ruff check + format check
make typecheck      # mypy टाइप चेकिंग
make ci-test        # तीनों (CI में उपयोग किया जाता है)

Pre-commit हुक्स इंस्टॉल होने पर कमिट पर स्वचालित रूप से चलते हैं:

make pre-commit-install   # Git हुक्स इंस्टॉल करें
make pre-commit           # सभी हुक्स मैन्युअली चलाएं

प्रोजेक्ट संरचना

scripts/
  download.py           # स्टेज 1: F5 से स्पेक्स प्राप्त करें
  validate.py           # स्टेज 2: लाइव API परीक्षण
  spectral_lint.py      # स्टेज 3/5: Spectral लिंटिंग एडाप्टर
  reconcile.py          # स्टेज 4: स्पेक्स में फिक्स लागू करें
  release.py            # स्टेज 6: रिलीज़ पैकेज
  generate_docs.py      # रिपोर्ट्स से MDX जनरेट करें
  utils/
    auth.py             # F5 XC API प्रमाणीकरण
    constraint_validator.py  # कंस्ट्रेंट परीक्षण + Discrepancy प्रकार
    report_generator.py      # रिपोर्ट फॉर्मेटिंग
    schemathesis_runner.py   # Schemathesis परीक्षण ऑर्केस्ट्रेशन
    spec_loader.py           # स्पेक I/O + JSON फॉर्मेटिंग

config/
  validation.yaml       # पाइपलाइन कॉन्फ़िगरेशन
  endpoints.yaml        # लाइव परीक्षण के लिए बेसलाइन एंडपॉइंट्स

spectral/
  functions/
    f5-path-params.js   # कस्टम Spectral फंक्शन

docs/                   # Starlight MDX डॉक्यूमेंटेशन
tests/                  # pytest टेस्ट सूट
release/specs/          # आउटपुट: रीकॉन्साइल्ड स्पेक फाइलें
reports/                # आउटपुट: सत्यापन और Spectral रिपोर्ट्स

नई फिक्स मेथड जोड़ना

रीकॉन्साइलर में एक नया Spectral ऑटो-फिक्स जोड़ने के लिए:

1. नियम जोड़ें .spectral.yaml में वांछित severity के साथ।

2. ऑटो-फिक्स सक्षम करें config/validation.yaml में spectral.auto_fix के अंतर्गत:

   spectral:
     auto_fix:
       your-new-rule: true

3. फिक्सर मेथड जोड़ें scripts/reconcile.py में SpecReconciler में:

   def _fix_your_rule(self, spec: dict, discrepancy: Discrepancy) -> dict | None:
       """Fix description."""
       # स्पेक को इन-प्लेस मॉडिफाई करें
       # यदि बदला गया तो spec लौटाएं, यदि कोई बदलाव आवश्यक नहीं तो None
       return spec

4. इसे रजिस्टर करें _apply_spectral_fix डिस्पैचर में:

   spectral_fixers = {
       # ... मौजूदा फिक्सर्स ...
       "spectral:your-new-rule": self._fix_your_rule,
   }

5. टेस्ट जोड़ें नई फिक्स मेथड को कवर करने के लिए।

नया Spectral नियम जोड़ना

JavaScript फंक्शन के साथ कस्टम Spectral नियम जोड़ने के लिए:

1. फंक्शन spectral/functions/your-rule.js में बनाएं। एक डिफॉल्ट फंक्शन एक्सपोर्ट करें जो (targetVal, options, context) प्राप्त करता है और {message, path} ऑब्जेक्ट्स की एक एरे लौटाता है।

2. इसे spectral-pipeline.yaml में रजिस्टर करें:

   functions:
     - f5-path-params
     - your-rule
   
   rules:
     your-rule:
       description: "What it checks"
       message: "{{error}}"
       severity: error
       given: "$.paths[*]"
       then:
         function: your-rule

सावधानी

कस्टम फंक्शन केवल spectral-pipeline.yaml में काम करते हैं। .spectral.yaml में functionsDir या functions न जोड़ें — वह कॉन्फ़िगरेशन Super-Linter और अन्य बाहरी टूल्स के साथ संगत रहना चाहिए।

CI पाइपलाइन

GitHub Actions वर्कफ़्लो (validate-and-release.yml) इन पर चलता है:

• शेड्यूल: प्रतिदिन सुबह 6 बजे UTC पर
• main पर पुश: जब scripts/, config/, या pyproject.toml में बदलाव हो
• मैन्युअल डिस्पैच: फोर्स्ड रिलीज़ या ड्राई-रन के विकल्पों के साथ

वर्कफ़्लो में चार जॉब्स हैं:

1. validate — स्पेक्स डाउनलोड करता है, सत्यापन चलाता है, Spectral लिंट, रीकॉन्साइल, Spectral गेट
2. check-release-needed — यह निर्णय लेने के लिए कंटेंट हैश की तुलना करता है कि रिलीज़ आवश्यक है या नहीं
3. release — पैकेज बनाता है और GitHub Release बनाता है (केवल यदि कंटेंट बदला हो)
4. update-docs — 01-validation-report.mdx पुनः जनरेट करता है और बदलाव होने पर PR खोलता है

एक notify जॉब किसी भी जॉब विफल होने पर GitHub इश्यू बनाता है।

ब्रांच और PR वर्कफ़्लो

सभी बदलाव इस प्रक्रिया का पालन करते हैं: इश्यू -> ब्रांच -> PR -> CI पास -> मर्ज।

• ब्रांच नाम: feature/<issue>-desc, fix/<issue>-desc, docs/<issue>-desc
• PR में एक इश्यू लिंक होना चाहिए (विवरण में Closes #N)
• आवश्यक CI चेक: Check linked issues और Lint Code Base
• स्क्वैश मर्ज प्राथमिक; मर्ज के बाद ब्रांचें स्वचालित रूप से हटती हैं

संपूर्ण वर्कफ़्लो नियमों के लिए CONTRIBUTING.md देखें।