Holarch

Başvuru

Tarif: Jira

Holarch gereksinimlerini REST API ile Jira sorunlarına bağlayın ve Jira sorunlarını Claude aracılığıyla incelenmiş Holarch değişikliklerine dönüştürün; kurulum, eşitleme betiği, çalışılmış bir örnek ve sorun giderme.

Nasıl kullanılır →

Bu sayfada
  1. Genel bakış
  2. Ön koşullar
  3. Nasıl kullanılır
    1. Ne zaman ve neden
    2. Eşitlemeyi kurma
    3. Onaylanmış gereksinimlerden Jira sorunları oluşturma
    4. Jira anahtarını Holarch'ta tutma (isteğe bağlı)
    5. Bir Jira sorununu Claude ile bir Holarch önerisine dönüştürme
    6. Uygulamalı örnek: CubeSat EO-1 demosu
    7. İpuçları
  4. Sorun giderme
  5. İlgili sayfalar

Genel bakış

Bu tarif, Jira'daki mühendislik çalışmasını Holarch'taki gereksinimlere bağlı tutar. İki bölümü vardır:

  • Holarch'tan Jira'ya (REST API): bir betik onaylanmış her gereksinim için bir Jira sorunu oluşturur. Her sorun Holarch'taki gereksinime geri bağlanır. İstediğiniz zaman yeniden çalıştırın: zaten sorunu olan gereksinimleri atlar.
  • Jira'dan Holarch'a (MCP, Claude aracılığıyla): Claude bir müşteri değişiklik talebi gibi bir Jira sorununu okur ve Holarch'ta karşılık gelen gereksinim değişikliklerini önerir. Siz öneriyi Holarch'ta inceleyip uygulayana kadar hiçbir şey değişmez.

Holarch'ın yerleşik bir Jira bağlayıcısı yoktur. Tarif REST API ve MCP kullanır, böylece her adımı uyarlayabilirsiniz.

Ön koşullar

  • API ve MCP içeren bir plan: Individual veya Team ya da Individual denemesi. Free planında doğrulanmış bir akademik e-posta adresine sahip veya etkin bir sınıf kuruluşundaki bir hesapta da bulunur (Planlar ve sınırlar).
  • Düzenleyicisi veya sahibi olduğunuz bir Holarch projesi. Öneriler düzenleyici rolü gerektirir.
  • Kişisel erişim belirteci: Hesap ayarları → API belirteçleri → Yeni belirteç. Holarch'tan Jira'ya betiği için Salt okunur kullanın ve onu projeyle sınırlayın (Belirteç oluşturma).
  • Jira Cloud: sorun oluşturabildiğiniz bir Jira projesi ve bir Atlassian API belirteci (Atlassian hesap ayarları → Security → API tokens). Jira Data Center bunun yerine /rest/api/2/ yollarını ve kişisel erişim belirtecini kullanır; API başvurusunu denetleyin.
  • Betik için requests paketiyle (python3 -m pip install requests) Python 3.9 veya sonrası.
  • Claude bölümü için: Holarch'a bağlı Claude (Holarch'ı Claude'a bağlama). Claude Jira sorunlarını yalnızca bir Jira bağlayıcısı da varsa kendisi okur; aksi halde sorun metnini konuşmaya yapıştırın.

Nasıl kullanılır

Ne zaman ve neden

Gereksinimler Holarch'ta bulunur; onları oluşturma ve test etme işi çoğu zaman Jira'da planlanır. İkisini bağlamak iki soruyu yanıtlar: “bu gereksinimi hangi Jira işi uyguluyor?” ve “bu değişiklik talebi hangi gereksinimlere dokunuyor?”. Eşitlemeyi her gereksinim incelemesinden sonra, yeni gereksinimler Approved durumuna ulaştığında çalıştırın.

Eşitlemeyi kurma

  1. Holarch'ta projeyle sınırlı bir Salt okunur belirteç oluşturun. Kopyalayın.
  2. Proje kimliğini bulun: GET /api/v1/projects projelerinizi id değerleriyle listeler.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. Betiğin okuduğu ortam değişkenlerini ayarlayın:
    • HOLARCH_TOKEN: Holarch belirteci.
    • HOLARCH_PROJECT: proje kimliği.
    • JIRA_URL: Jira siteniz, örneğin https://your-site.atlassian.net.
    • JIRA_EMAIL ve JIRA_API_TOKEN: Atlassian oturum açma e-postanız ve API belirteciniz.
    • JIRA_PROJECT: Jira proje anahtarı, örneğin EO.
  2. Aşağıdaki betiği holarch_to_jira.py olarak kaydedin.

Onaylanmış gereksinimlerden Jira sorunları oluşturma

Betik her gereksinimi REST API üzerinden okur, zaten Jira sorunu olanları atlar ve Durum değeri Approved olan kalan her gereksinim için bir Task oluşturur.

# holarch_to_jira.py: one Jira issue per approved Holarch requirement. Safe to run again.
import os

import requests

HOLARCH = os.environ.get("HOLARCH_URL", "https://app.holarch.app") + "/api/v1"
PROJECT = os.environ["HOLARCH_PROJECT"]
HEADERS = {"Authorization": "Bearer " + os.environ["HOLARCH_TOKEN"]}
JIRA = os.environ["JIRA_URL"].rstrip("/")
JIRA_AUTH = (os.environ["JIRA_EMAIL"], os.environ["JIRA_API_TOKEN"])
JIRA_PROJECT = os.environ["JIRA_PROJECT"]


def holarch(method, path, **kw):
    r = requests.request(method, HOLARCH + path, headers=HEADERS, timeout=60, **kw)
    if r.status_code >= 400:
        d = r.json()
        raise SystemExit(f"Holarch answered {r.status_code} {d.get('code')}: {d.get('error')}")
    return r.json()


def requirements():
    offset = 0
    while True:
        page = holarch("GET", f"/projects/{PROJECT}/entities",
                       params={"class": "Requirement", "limit": 500, "offset": offset})
        yield from page["entities"]
        offset += page["limit"]
        if offset >= page["total"]:
            return


def linked_in_jira():
    """The Jira labels holarch-<requirement id> already on issues of the Jira project."""
    seen, token = set(), None
    while True:
        params = {"jql": f'project = "{JIRA_PROJECT}" AND labels = holarch', "fields": "labels", "maxResults": 100}
        if token:
            params["nextPageToken"] = token
        r = requests.get(JIRA + "/rest/api/3/search/jql", params=params, auth=JIRA_AUTH, timeout=60)
        r.raise_for_status()
        d = r.json()
        for issue in d.get("issues", []):
            seen.update(x for x in issue["fields"]["labels"] if x.startswith("holarch-"))
        token = d.get("nextPageToken")
        if not token:
            return seen


seen = linked_in_jira()
for req in requirements():
    if "holarch-" + req["id"] in seen:
        continue
    e = holarch("GET", f"/projects/{PROJECT}/entities/{req['id']}")["entity"]
    if e["attributes"].get("Status") != "Approved":
        continue
    text = (e["description"] + "\n\n" if e["description"] else "") + "Requirement in Holarch: " + e["url"]
    fields = {
        "project": {"key": JIRA_PROJECT},
        "issuetype": {"name": "Task"},
        "summary": f"{e['number']} {e['name']}".strip(),
        "labels": ["holarch", "holarch-" + e["id"]],
        "description": {"type": "doc", "version": 1, "content": [
            {"type": "paragraph", "content": [{"type": "text", "text": text}]}]},
    }
    issue = requests.post(JIRA + "/rest/api/3/issue", json={"fields": fields}, auth=JIRA_AUTH, timeout=60)
    issue.raise_for_status()
    key = issue.json()["key"]
    print(f"{e['number']} {e['name']} -> {key}")
  1. python3 holarch_to_jira.py çalıştırın.

    Her yeni sorun için bir satır görürsünüz, örneğin 2.1 Pointing Accuracy -> EO-12.

Nasıl çalışır:

  • GET /api/v1/projects/<project>/entities?class=Requirement gereksinimleri her seferinde 500 tane olmak üzere listeler.
  • GET /api/v1/projects/<project>/entities/<id> her gereksinimin özniteliklerini (burada Durum) ve onu Holarch'ta açan bağlantı olan url değerini verir.
  • Her sorun holarch ve holarch-<id> Jira etiketlerini alır. Sonraki çalıştırma onları bir Jira aramasıyla bulur ve bu gereksinimleri atlar.
  • Gereksinimler yalnızca okunur. Betik Holarch'ta hiçbir şeyi değiştirmez.

Jira anahtarını Holarch'ta tutma (isteğe bağlı)

Jira anahtarını Holarch'taki gereksinimde görmek için bir metin özniteliği ekleyin ve anahtarı ona yazın.

  1. Holarch'ta Ayarlar → Şema açın, Requirement seçeneğine tıklayın ve Kısa metin türünde Jira Key adlı bir öznitelik ekleyin (Bir sınıfa öznitelik ekleme).
  2. Betik için salt okunur belirteç yerine bir Okuma ve yazma belirteci oluşturun.
  3. Betiğin son döngüsünün sonunda, print(…) satırından sonra şunu ekleyin:
    holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})

Değişiklik uygulamadaki bir düzenleme gibi yazılır: sizin adınızla kaydedilir ve projeyi açık tutan herkes onu görür. Bu özniteliği ayarlamak onaylanmış bir gereksinimi incelemeye geri göndermez. Proje konfigürasyon kontrolü kullandığında onaylanmış gereksinimler doğrudan değişiklikleri reddeder (409 change-control); anahtarı yalnızca Jira'da tutun veya değişikliği bir değişiklik talebiyle yapın.

Bir Jira sorununu Claude ile bir Holarch önerisine dönüştürme

Bir Jira sorunu bir gereksinim değişikliği istediğinde, örneğin bir değeri sıkılaştırmaya yönelik bir müşteri talebinde bunu kullanın.

  1. Okuma ve değişiklik önerme erişimiyle Holarch'a bağlı Claude'u açın.
  2. Örneğin şunu sorun: “EO-31 Jira sorununu oku. CubeSat projesinde etkilediği Holarch gereksinimlerini bul ve istediği değişiklikleri öner. Öneri özetinde EO-31'den bahset.”

    Jira bağlayıcısı yoksa bunun yerine sorunun özetini ve açıklamasını iletiye yapıştırın.

  3. Claude projeyi list_projects, search_entities ve get_entity ile okur. Her değişikliği update_entity ile (veya yeni gereksinimler için create_entity ve relate ile) bir öneriye ekler, ardından onu propose_changes ile gönderir.

    Claude önerinin başlığı ve onu incelemek için bir bağlantıyla yanıt verir.

  4. Holarch'ta ✦ YZ ▾ → “<title>” incele… veya zil simgesinin altındaki bildirimi açın.
  5. Her değişikliği denetleyin. İstemediklerinizin işaretini kaldırın, ardından Seçilenleri uygula seçeneğine tıklayın.

    Değişiklikler uygulanır ve tek bir Geri al ile hepsi geri alınır. Değişen gereksinim metni izleme bağlantılarını incelemeye işaretler ve onaylanmış bir gereksinim her düzenlemede olduğu gibi In Review durumuna geri döner.

Betikler aynı öneriyi Claude olmadan yapabilir: her değişiklik için bir kez POST /api/v1/projects/<project>/proposal/changes, ardından bir title ve summary ile POST /api/v1/projects/<project>/proposal.

curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"op": "update", "entity": "<requirement id>", "description": "The ADCS shall point the payload boresight within 0.08 degrees of the commanded target."}' \
  https://app.holarch.app/api/v1/projects/<project>/proposal/changes
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"title": "EO-31: tighter pointing", "summary": "Customer request EO-31 tightens pointing accuracy to 0.08 degrees."}' \
  https://app.holarch.app/api/v1/projects/<project>/proposal

Uygulamalı örnek: CubeSat EO-1 demosu

  1. Demoyu Projeleri yönet → Proje dosyaları ▾ → Yeni demo proje ile oluşturun.
  2. Demo projesiyle sınırlı salt okunur bir belirteç oluşturun ve holarch_to_jira.py betiğini bir test Jira projesine karşı çalıştırın.

    Onaylanmış her gereksinim bir sorun alır, örneğin “The ADCS shall point the payload boresight within 0.1 degrees of the commanded target.” metni ve gereksinime bağlantıyla 2.1 Pointing Accuracy.

  3. Betiği yeniden çalıştırın.

    Hiçbir şey yazdırmaz: onaylanmış her gereksinimin zaten sorunu var.

  4. Jira'da 0.1 derece yerine 0.08 derece isteyen bir EO-31 sorunu oluşturun. Yukarıdaki gibi Claude'dan değişikliği önermesini isteyin.
  5. Holarch'ta öneriyi inceleyin. 2.1 Pointing Accuracy metnini değiştirir ve Etki listesi onu doğrulayan TC-04 Pointing Accuracy Test öğesini gösterir.

İpuçları

  • Eşitleme betiğine projeyle sınırlı kendi salt okunur belirtecini verin. Claude'a ayrı bir bağlantı verin.
  • Belirteçleri gizli bilgi deponuzda veya ortamınızda tutun, asla betikte tutmayın.
  • Bir sprint'in arkasındaki gereksinimleri Jira'da holarch etiketiyle arayın.
  • Gereksinim numaraları değişebilir; holarch-<id> etiketi değişmez. Özetteki numaraya göre değil, etikete göre eşleştirin.

Sorun giderme

İleti veya belirtiNeden ve çözüm
Holarch answered 401 token-invalidBelirteç yanlış, iptal edilmiş veya süresi dolmuş. Hesap ayarları → API belirteçleri altında yeni bir tane oluşturun.
Holarch answered 403 plan-apiHesabın planı API ve MCP'yi içermiyor. Individual denemesini başlatın veya bir plan seçin; belirteç ardından yeniden çalışır.
Holarch answered 403 org-policyProjenin kuruluşu API erişimini kapattı. Bir kuruluş yöneticisine sorun.
Holarch answered 403 read-only-tokenJira Key yazması bir Okuma ve yazma belirteci gerektirir.
Holarch answered 400 unknown-attributeProjede Requirement için Jira Key özniteliği yok. Onu Ayarlar → Şema içinde ekleyin veya isteğe bağlı adımı bırakın.
Holarch answered 409 change-controlGereksinim konfigürasyon kontrolü altında. Onu bir değişiklik talebiyle değiştirin veya anahtarı yalnızca Jira'da tutun.
Holarch answered 429 rate-limitedDakikada 600'den fazla istek veya 120 değişiklik. Retry-After içindeki saniye kadar bekleyin, ardından yeniden çalıştırın; tamamlanmış sorunlar atlanır.
Jira 400 yanıtı veriyorJira sorun alanlarını reddetti, örneğin projede olmayan bir sorun türü. Task yerine projenin sorun türlerinden birini kullanın.
Jira 401 veya 403 yanıtı veriyorJIRA_EMAIL, JIRA_API_TOKEN ve Jira projesinde sorun oluşturma izninizi denetleyin.
Claude Holarch yazma araçlarını göstermiyorBağlantı salt okunur. Okuma ve değişiklik önerme ile yeniden bağlanın, ardından yeni bir konuşma başlatın.