परियोजना का इतिहास

कामकाजी प्रति और इतिहास

एप्लिकेशन के SQLite रिकॉर्ड वर्तमान प्रोजेक्ट वर्किंग कॉपी हैं। @cadcamfun/vcs एक इंजेक्टेड ऑब्जेक्ट बैकएंड के माध्यम से गिट-संगत ब्लॉब्स, पेड़, कमिट और रेफरी को संग्रहीत करता है; साइडकार SQLite में उस बैकएंड को बनाए रखता है। इतिहास संचालन Git निष्पादन योग्य या GitHub खाते के बिना स्थानीय रूप से काम करता है।

एक प्रतिबद्धता परियोजना और उससे संबंधित डिज़ाइन/विनिर्माण संसाधनों का स्नैपशॉट लेती है। शाखाएँ कमिट की ओर इशारा करती हैं, जबकि HEAD चेक-आउट शाखा की पहचान करता है। संसाधन संस्करण तालिकाएँ इस परियोजना-स्तरीय इतिहास के साथ सह-अस्तित्व में हैं; एक ड्राइंग संस्करण और एक प्रोजेक्ट कमिट के अलग-अलग दायरे होते हैं।

प्रतिबद्धता और शाखा कार्यप्रवाह

1. पढ़ना GET /api/projects/:id/vcs/status वर्तमान शाखा, HEAD और परिवर्तित पथ देखने के लिए।
2. के साथ एक शाखा बनाएं POST /vcs/branches, फिर इसकी जांच करें POST /vcs/checkout. यहां शाखा पथ परियोजना के एपीआई उपसर्ग से संबंधित हैं।
3. प्रोजेक्ट संसाधनों को संपादित करें और इसके साथ प्रतिबद्ध हों POST /vcs/commit और एक गैर-खाली संदेश.
4. निरीक्षण करें GET /vcs/log और GET /vcs/diff. लॉग एक संशोधन, सीमा और वैकल्पिक ट्रैक किए गए पथ का समर्थन करता है।
5. प्रोजेक्ट पुल अनुरोध खोलें, इसके संरचनात्मक परिवर्तनों की समीक्षा करें, और अवरुद्ध समीक्षाओं या विरोधों को हल करने के बाद विलय करें।

चेकआउट, पुनर्स्थापना, और संचालन जो कार्यशील शाखा को स्थानांतरित करते हैं, जहां आवश्यक हो वहां गंदी कार्यशील प्रतिलिपि को अस्वीकार कर देते हैं। पुनर्स्थापना पिछली सामग्री का प्रतिनिधित्व करने वाली एक नई प्रतिबद्धता को रिकॉर्ड करती है, जो वैकल्पिक रूप से चयनित पथों तक सीमित होती है। यह बाद के इतिहास को दोबारा लिखने के बजाय संरक्षित करता है।

स्नैपशॉट सामग्री

project.json
drawings/<id>.json
components/<id>.json
toolpaths/<id>.json
materials/<id>.json
tools/<id>.json
machine-configs/<id>.json
costs/<id>.json
.cadcamfun/workflows/<name>.yml

प्रति इकाई एक JSON फ़ाइल असंबंधित परिवर्तनों को अलग रखती है। स्नैपशॉट में टूलपाथ और उत्पादन लागत अनुमानों द्वारा संदर्भित लाइब्रेरी आइटम शामिल हैं ताकि पुनर्स्थापित विनिर्माण डेटा अपनी निर्भरता बनाए रख सके। फ़ाइल नाम के रूप में उपयोग किए जाने वाले इकाई पहचानकर्ता अधिकतम 128 वर्णों के साथ सुरक्षित अक्षरों, अंकों, अंडरस्कोर और हाइफ़न तक सीमित हैं।

JSON कुंजियाँ पुनरावर्ती रूप से क्रमबद्ध की जाती हैं और फ़ाइलें अंतिम न्यूलाइन के साथ स्थिर सुंदर-मुद्रण का उपयोग करती हैं। ऐरे अपना क्रम बनाए रखते हैं। अतिरिक्त टेक्स्ट फ़ाइलें पैकेज-स्तरीय स्नैपशॉट के साथ यात्रा कर सकती हैं; सार्वजनिक प्रतिबद्ध समापन बिंदु केवल इसके अंतर्गत अतिरिक्त फ़ाइलें स्वीकार करता है .cadcamfun/workflows/ सुरक्षित YAML फ़ाइल नाम के साथ.

ऑब्जेक्ट बाइट के लिए गिट के ढीले-ऑब्जेक्ट प्रारूप बाइट का उपयोग करते हैं, इसलिए ऑब्जेक्ट आईडी उन लोगों से मेल खाते हैं जिनकी गणना की गई है git. ट्री प्रविष्टियाँ या तो फ़ाइलें हैं (मोड 100644) या निर्देशिकाएँ (मोड 40000). एक प्रतिबद्ध हस्ताक्षर नाम, ईमेल, यूनिक्स-सेकेंड समय और ए रिकॉर्ड करता है +hhmm/-hhmm ऑफसेट शाखाओं को नीचे संग्रहित किया जाता है refs/heads/, और एक प्रोजेक्ट की डिफ़ॉल्ट शाखा है main (packages/vcs/src/object.ts, repository.ts).

अंतर और विलय शब्दार्थ

रिपॉजिटरी एक मर्ज बेस की गणना करता है, अपरिवर्तित पक्षों को सीधे संभालता है, और बदले हुए JSON के लिए संरचनात्मक तीन-तरफ़ा मर्ज करता है। स्वतंत्र ऑब्जेक्ट-प्रॉपर्टी संपादन बिना किसी विरोध के विलय कर सकते हैं। समान स्केलर या सरणी में समवर्ती असंगत संपादन JSON पॉइंटर्स के माध्यम से रिपोर्ट किए जाते हैं; सरणियों को तत्व दर तत्व मर्ज नहीं किया जाता है।

इकाई अंतर में पथ, संसाधन प्रकार, पहचानकर्ता और उपलब्ध होने पर नाम, जोड़ा/संशोधित/हटाया गया स्थिति, और पहले/बाद के मूल्यों के साथ संपत्ति परिवर्तन शामिल हैं। गैर-JSON फ़ाइलें फ़ाइल-स्तरीय विरोध व्यवहार का उपयोग करती हैं। संघर्षों के साथ एक रिपॉजिटरी मर्ज मर्ज किए गए कमिट को लिखे बिना उनके पथ और पॉइंटर्स लौटाता है।

अनुरोध और अनुमतियाँ खींचें

प्रोजेक्ट पुल अनुरोध यहां रहते हैं /api/projects/:id/pulls. इसे खोलने पर शीर्षक, मुख्य भाग, सिर, आधार और लेखक का प्रकार रिकॉर्ड होता है। विस्तृत प्रतिक्रियाओं में पुल अनुरोध, समीक्षाएं और परिवर्तन शामिल हैं। समीक्षा समर्थन comment, approve, और request-changes, वैकल्पिक पथ और संपत्ति सूचक के साथ।

प्रति समीक्षक नवीनतम गैर-टिप्पणी निर्णय अनुरोध-परिवर्तन ब्लॉक को नियंत्रित करता है। विलय से इनकार कर दिया जाता है जबकि ऐसे किसी भी फैसले में बदलाव का अनुरोध किया जाता है। जब कोई अवरोधक निर्णय न हो तो कार्यान्वयन के लिए सकारात्मक अनुमोदन की आवश्यकता नहीं होती है। मर्ज किए गए पुल-अनुरोध में रिकॉर्ड किए गए मर्ज कमिट का उपयोग होता है ताकि बाद में शाखा आंदोलन उस समीक्षा रिकॉर्ड को न बदले।

इतिहास पढ़ना, कमिट करना, ब्रांचिंग करना, पुल अनुरोध खोलना और समीक्षा करने के लिए प्रोजेक्ट एक्सेस की आवश्यकता होती है। वर्किंग-कॉपी चाल और साझा-शाखा रखरखाव के लिए मालिक या संगठन व्यवस्थापक/प्रबंधक की आवश्यकता होती है, जैसा कि हैंडलर द्वारा लागू किया जाता है। गंदे या परस्पर विरोधी ऑपरेशन रिटर्न 409; संरक्षित कार्रवाइयां रिटर्न 403; गुम रेफरी या संसाधन रिटर्न 404; अन्य अमान्य परिचालन रिटर्न 400।

कोई एआई अभिनेता प्रतिबद्ध, पुनर्स्थापित या विलय नहीं कर सकता है main. सहायक एक प्रस्ताव शाखा का उपयोग करता है और किसी व्यक्ति की समीक्षा के लिए एक पुल अनुरोध खोलता है। ऑडिट और अधिसूचना रिकॉर्ड सहायक-उत्पन्न परिवर्तनों की पहचान करते हैं।

वैकल्पिक GitHub दर्पण

GET और PUT /api/projects/:id/vcs/remote पढ़ें या सेट करें owner/repo गिटहब दर्पण; शून्य इसे अलग कर देता है। धक्का देने और खींचने का उपयोग POST /vcs/push और /vcs/pull, उपयोगकर्ता के GitHub टोकन के साथ x-github-token उस कॉल के लिए.

पुश पहुंच योग्य वस्तुओं को स्थानांतरित करता है और अनपुल्ड रिमोट कमिट्स को ओवरराइट किए बिना रिमोट ब्रांच को अपडेट करता है। पुल दूरस्थ शाखा को लाता है और गंदी कार्यशील प्रतिलिपि को अस्वीकार करते हुए इसे स्थानीय रूप से मर्ज करता है। भिन्न-भिन्न असंगत JSON स्थानीय सामग्री को चुपचाप प्रतिस्थापित करने के बजाय रिटर्न विरोधों को संपादित करता है।

साइडकार ट्रांसपोर्ट GitHub REST ऑब्जेक्ट/रेफ ऑपरेशंस का उपयोग करता है। GitHub टोकन प्रति अनुरोध प्रदान किया जाता है और इसे प्रोजेक्ट डेटा के रूप में संग्रहीत नहीं किया जाता है। स्थानीय पुल अनुरोध एक एप्लिकेशन समीक्षा रिकॉर्ड है; यह स्वचालित रूप से GitHub पुल अनुरोध नहीं है।

स्नैपशॉट और पुनर्स्थापना

snapshotToFiles किसी प्रोजेक्ट स्नैपशॉट को कैनोनिकल फ़ाइल सामग्री में परिवर्तित करता है; filesToSnapshot डोमेन सूचियों का पुनर्निर्माण करता है। ProjectVcsRepo वर्तमान डेटाबेस संसाधनों को पढ़ता है और पुनर्स्थापित स्नैपशॉट लागू करता है। संपूर्ण-प्रोजेक्ट पुनर्स्थापना कई संबंधित तालिकाओं को बदल सकती है, इसलिए इतिहास बदलने से पहले इसके अंतर की समीक्षा करें और कार्यशील प्रतिलिपि साफ़ करें।

परिवहन और ऑब्जेक्ट एपीआई

वीसीएस पैकेज ऑब्जेक्ट एन्कोडिंग और रीडिंग निर्यात करता है, Repository, स्टोर एडाप्टर, कैनोनिकल JSON और मर्ज हेल्पर्स, स्नैपशॉट रूपांतरण, इकाई अंतर, GitHub सिंक्रनाइज़ेशन और ट्रांसपोर्ट इंटरफ़ेस। परीक्षण उपयोगकर्ता के भंडार तक पहुंचने के बजाय इन-मेमोरी ऑब्जेक्ट बैकएंड या नकली ट्रांसपोर्ट को इंजेक्ट कर सकते हैं।

कार्यान्वयन प्रवेश बिंदु

packages/vcs/src/repository.ts कमिट, रेफरी, ट्रैवर्सल, रेस्टोरेशन और मर्ज का मालिक है; json.ts संरचनात्मक विलय का मालिक है; snapshot.ts ट्रैक किए गए संसाधनों को परिभाषित करता है; diff.ts इकाई परिवर्तन का वर्णन करता है; github.ts और transport.ts मिररिंग लागू करें. साइडकार project-vcs.ts अभिनेता नीति और दृढ़ता जोड़ता है, जबकि http/vcs.ts परिवहन प्राधिकरण और घटनाओं की आपूर्ति करता है।

इतिहास संचालन और स्वचालन

वर्कफ़्लो परिभाषाएँ प्रोजेक्ट के साथ संस्करणित की जाती हैं और प्रतिबद्ध फ़ाइलों के विरुद्ध चलती हैं। इतिहास दर्ज होने के बाद एक प्रतिबद्धता उन वर्कफ़्लो को ट्रिगर कर सकती है; एक असफल वर्कफ़्लो प्रतिबद्धता को पूर्ववत नहीं करता है। किसी प्रोजेक्ट की स्थिति का निदान करते समय स्थानीय संसाधन बचत, प्रोजेक्ट कमिट, वर्कफ़्लो परिणाम और रिमोट सिंक्रोनाइज़ेशन को अलग रखें।

एप्लिकेशन डेटा के बिना रिपॉजिटरी का प्रयास करें

ऑब्जेक्ट-स्टोर सीम एक एकीकरण अभ्यास को पूरी तरह से मेमोरी में प्रतिबद्ध और शाखाओं में बदलने देता है। इसे किसी कार्यस्थान के अंदर चलाएँ जो इस पर निर्भर करता है @cadcamfun/vcs, जैसे कि apps/sidecar. यह डेस्कटॉप के प्रोजेक्ट डेटाबेस को नहीं छूता है।

import { Repository, memoryBackend, canonicalJson } from "@cadcamfun/vcs"

const repo = new Repository(memoryBackend())
const author = { name: "Workshop", email: "workshop@example.invalid", time: 0, tz: "+0000" }
repo.commit({ "project.json": canonicalJson({ name: "Blank", revision: 1 }) }, {
  message: "Initial blank", author
})
repo.createBranch("proposal/wider-blank")
repo.checkout("proposal/wider-blank")
repo.commit({ "project.json": canonicalJson({ name: "Blank", revision: 2 }) }, {
  message: "Record revised blank", author
})
console.log(repo.currentBranch()) // proposal/wider-blank
console.log(repo.log().length) // 2

Repository.commit उस कमिट के लिए संपूर्ण फ़ाइल ट्री प्राप्त होता है, पैच नहीं। साइडकार इस ट्री को कार्यशील डेटाबेस रिकॉर्ड और ले जाने वाली टेक्स्ट फ़ाइलों से बनाता है। एक पैकेज-स्तरीय एकीकरण को उन फ़ाइलों को संरक्षित करना होगा जिन्हें वह बनाए रखना चाहता है। इन-मेमोरी उदाहरण साइडकार स्वामित्व या एआई अभिनेता नीति लागू नहीं करता है; इन्हें प्रोजेक्ट सेवा और HTTP परत द्वारा लागू किया जाता है।

स्रोत: packages/vcs/src/store.ts, repository.ts, और apps/sidecar/src/services/project-vcs.ts.

जानबूझकर समीक्षा करें, पुनर्स्थापित करें और सिंक्रनाइज़ करें

शाखाओं को बदलने से पहले कामकाजी परिवर्तनों को रिकॉर्ड करें। एक नई शाखा के लिए एक समाधान योग्य स्रोत प्रतिबद्धता की आवश्यकता होती है, इसलिए शाखा लगाने से पहले अपनी पहली प्रतिबद्धता के साथ एक अप्रतिबद्ध परियोजना को प्रारंभ करें। एक शाखा बनाने से केवल एक रेफरी बनता है; चेकआउट एक अलग ऑपरेशन है जो अपने स्नैपशॉट को कार्यशील डेटाबेस पर लागू करता है।

पुल अनुरोध के लिए, उसके मर्ज आधार के विरुद्ध शीर्ष की तुलना करें और संपत्ति-स्तर के अंतरों की समीक्षा करें। बाद की टिप्पणी पिछले अनुरोध-परिवर्तन के फैसले को स्पष्ट नहीं करती है: समीक्षक को बाद में स्वीकृत फैसले को प्रस्तुत करना होगा। एक मर्ज किया गया पीआर रिपॉजिटरी वंश के अनुसार तेजी से आगे बढ़ सकता है या मर्ज कमिट बना सकता है; माता-पिता की निश्चित संख्या मानने के बजाय रिकॉर्ड की गई मर्ज कमिट का निरीक्षण करें।

चेक-आउट आधार में विलय करते समय, सेवा को एक साफ़ कार्यशील प्रतिलिपि की आवश्यकता होती है और नया आधार स्नैपशॉट लागू होता है। जब किसी अन्य शाखा की जांच की जाती है, तो पीआर के आधार को मर्ज करने से वर्तमान कार्यशील डेटाबेस को प्रतिस्थापित किए बिना उस शाखा का रेफरी अपडेट हो जाता है। बाद का चेकआउट उस अद्यतन आधार को लोड करता है।

पुश और पुल प्रतिबद्ध इतिहास को सिंक्रनाइज़ करें। सहेजे न गए यूआई सामग्री और अप्रतिबद्ध डेटाबेस स्थिति दूरस्थ स्नैपशॉट नहीं हैं। रिमोट-फ़ॉरवर्ड अस्वीकृति पहले लाने/विलय करने का अनुरोध है; यह दूरस्थ शाखा को अधिलेखित करने का निर्देश नहीं है।

स्रोत: packages/vcs/src/repository.ts, github.ts, और apps/sidecar/src/services/project-vcs.ts.

इतिहास की असफलताओं से उबरें

स्रोत: packages/vcs/src/repository.ts, apps/sidecar/src/services/project-vcs.ts, और http/vcs.ts. एपीआई संदर्भ वास्तविक अनुरोध और प्रतिक्रिया स्कीमा सूचीबद्ध करता है।

रिपॉजिटरी लेआउट

एक प्रोजेक्ट को रिपॉजिटरी में प्रति इकाई एक JSON फ़ाइल के रूप में संग्रहीत किया जाता है। इसलिए किसी ड्राइंग को संपादित करना कभी भी टूलपाथ फ़ाइल को नहीं छूता है, और लेआउट GitHub पर स्वाभाविक रूप से पढ़ता है। snapshotToFiles इस लेआउट को a से लिखता है ProjectSnapshot, और filesToSnapshot इसे वापस पढ़ता है.

कोड में प्रतिबद्ध, शाखा, अंतर और विलय करें

The Repository क्लास किसी भी स्टोरेज बैकएंड पर काम करता है। साइडकार इसे SQLite (टेबल्स) के साथ सपोर्ट करता है GitObject और GitRef); memoryBackend() परीक्षणों और प्रयोगों के लिए उपयोग किया जाता है। निम्नलिखित उदाहरण पूर्ण है और इसका आउटपुट टिप्पणियों में दिखाया गया है।

import { Repository, memoryBackend, snapshotToFiles, describeDiff } from "@cadcamfun/vcs"

const repo = new Repository(memoryBackend())
const me = { name: "Ada", email: "ada@example.com", time: 1767225600, tz: "+0100" }
const files = (width: number, height: number) => snapshotToFiles({
  project: { id: "p1", name: "Bracket" },
  drawings: [{ id: "d1", name: "Plate", width, height }],
  components: [], toolpaths: [],
})

const base = repo.commit(files(40, 25), { message: "base", author: me })
repo.currentBranch()                    // "main"

repo.createBranch("a"); repo.createBranch("b")
repo.checkout("a"); const a = repo.commit(files(50, 25), { message: "a: width 50", author: me })
repo.checkout("b"); repo.commit(files(40, 30), { message: "b: height 30", author: me })

describeDiff(repo, base, a)
// [{ path: "drawings/d1.json", kind: "drawings", id: "d1", name: "Plate",
//    status: "modified", changes: [{ pointer: "/width", before: 40, after: 50 }] }]

repo.mergeInto("a", "b", me)            // { kind: "merge", oid: "46e7…" }
// different properties of the same entity merge cleanly

repo.checkout("b"); repo.commit(files(60, 30), { message: "b: width 60", author: me })
repo.mergeInto("a", "b", me)
// { kind: "conflict", conflicts: [{ path: "drawings/d1.json", pointers: ["/width"] }] }

repo.createBranch("bad..name")          // throws: Invalid branch name bad..name
repo.commit(sameFilesAsHead, { message: "x", author: me })
// throws: No changes since the last commit   (unless allowEmpty: true)

JSON संपत्तियों के स्तर पर विलय तीन-तरफा होते हैं। जब दोनों पक्षों ने एक इकाई के विभिन्न गुणों को बदल दिया, तो विलय सफल हो गया। जब दोनों ने एक ही संपत्ति को अलग-अलग मूल्यों में बदल दिया, तो परिणाम एक है conflict जो प्रत्येक फ़ाइल के अंदर RFC 6901 पॉइंटर्स को सूचीबद्ध करता है। प्रति सूचकांक समान लंबाई की सरणियों की तुलना की जाती है, इसलिए एक स्थानांतरित शीर्ष एक परिवर्तन के रूप में दिखाई देता है; विभिन्न लंबाई की सरणियों की समग्र रूप से तुलना की जाती है।

आवेदन द्वारा लागू नियम

साइडकार की प्रोजेक्ट इतिहास सेवा रिपॉजिटरी के शीर्ष पर नियम जोड़ती है:

प्रत्येक समीक्षक का केवल नवीनतम गैर-टिप्पणी निर्णय ही मायने रखता है। एक समीक्षक जिसने परिवर्तनों का अनुरोध किया और बाद में मंजूरी दे दी, वह अब मर्ज को नहीं रोकता है। कमिट, पुल रिक्वेस्ट इवेंट और समीक्षाएँ लाइव इवेंट के रूप में प्रकाशित की जाती हैं, इसलिए डेस्कटॉप और साथी मतदान के बिना अपडेट होते हैं।

एक वास्तविक प्रतिबद्ध वस्तु

{
  "oid": "44d2d03d23b27fbbc4b388e32e15dfb0f39fff87",
  "parents": [],
  "message": "First version\n",
  "author": { "name": "Local user", "email": "local@cadcamfun.local", "time": 1792037121 }
}

• oid संग्रहित कमिट ऑब्जेक्ट की एक 40-अक्षर हेक्स आईडी है GitObject.
• पहली प्रतिबद्धता का कोई माता-पिता नहीं है; एक मर्ज कमिट में दो होते हैं।
• संदेश को पिछली नई लाइन के साथ संग्रहीत किया जाता है, जैसा कि Git करता है।
• बिना एक x-session-token, लेखक संस्थापन का स्थानीय प्रोफ़ाइल है। time यूनिक्स सेकंड में है.

3डी में