वर्कफ्लो टेम्पलेट

यह दस्तावेज़ बताता है कि GitHub Actions (GHA) का उपयोग करके किसी Exercism भाषा ट्रैक के लिए Continuous Integration (CI) वर्कफ्लो कैसे सेट अप करें। इसमें आपके लिए कुछ बेहतरीन तरीके और उदाहरण दिए गए हैं, जिन्हें इस्तेमाल करके आप अपने तेज़, भरोसेमंद और मज़बूत CI वर्कफ्लो बना सकते हैं। इस फोल्डर में मौजूद GHA वर्कफ्लो को किसी भी CI के साथ काम करने लायक बदला जा सकता है, क्योंकि मूल ढाँचा वही रहता है।

यह:

• आदर्श CI वर्कफ्लो की रूपरेखा देगा
• विचारणीय बातों और सुझावों पर चर्चा करेगा
• इस्तेमाल के लिए कुछ टेम्पलेट देगा
• अंत में Travis से माइग्रेट करने की गाइड देगा

इन वर्कफ्लो फाइलों का उदाहरण आप exercism/javascript में देख सकते हैं।

मदद: यह काम बहुत ज़्यादा लग रहा है 😓

बाकी दस्तावेज़ यह समझाने के लिए है कि ये वर्कफ्लो कैसे काम करते हैं। अगर आपको जल्दी है और आप PR स्क्रिप्ट बेहतर किए बिना सिर्फ Travis या Circle से GHA पर शिफ्ट होना चाहते हैं, तो Travis से माइग्रेट करना पर हमारी ~10 मिनट की गाइड देखिए।

ट्रैक के CI एक्शन

आपके रिपॉज़िटरी की सामग्री की अखंडता जाँचने के लिए सुझाए गए एक्शन ये हैं:

1. config.json की जाँच के लिए configlet लिंटिंग
2. स्टब की जाँच
3. डॉक्युमेंटेशन की जाँच (v3 में नई फाइलें ज़रूरी हैं; यह शायद configlet में चला जाए)
4. "मेंटेनर" कॉन्फिगरेशन का उपयोग करके अभ्यासों की लिंटिंग
5. उदाहरण/एक्ज़ेम्प्लर फाइलों का उपयोग करके अभ्यासों का परीक्षण (इसमें बिल्ड स्टेप भी शामिल हो सकता है)

ट्रैक-विशेष एक्शन भी हो सकते हैं। उदाहरण के लिए:

1. अभ्यास कॉन्फिगरेशन की अखंडता की जाँच
2. अभ्यास फाइलों की फॉर्मेटिंग की जाँच

और शायद आप काम आसान करने वाली कुछ और जाँच भी चाहेंगे, जैसे:

1. सुनिश्चित करना कि CONTRIBUTING मौजूद है
2. सुनिश्चित करना कि डिपेंडेंसी के लिए एक ठीक लॉकफाइल मौजूद है
3. सुनिश्चित करना कि markdown फाइलों के अंदर के लिंक सही हैं
4. ...

सुझाव

जाँच कितनी बार चलानी चाहिए

हर एक्शन के बारे में सोचिए कि वह कितनी बार चलना चाहिए।

• configlet लिंटिंग बहुत ज़रूरी है (क्योंकि config.json खराब होने पर पूरा ट्रैक टूट सकता है), इसलिए यह शायद हमेशा चलनी चाहिए, लेकिन इसे हर कमिट पर सिर्फ एक बार चलाने की ज़रूरत है।
• फाइलों का होना या उनकी अखंडता की जाँच हर कमिट पर सिर्फ एक बार चलानी होती है।
• अगर किसी ट्रैक को कई रनटाइम वर्शन या कंपाइलर वर्शन पर चलना है, तो अभ्यासों का बिल्ड/परीक्षण हर समर्थित वर्शन के लिए चलाया जाना चाहिए।
• PR में शायद सिर्फ जोड़ी या बदली गई फाइलों पर ही एक्शन चलाने की ज़रूरत होती है, लेकिन क्योंकि एक फाइल पूरे अभ्यास को प्रभावित कर सकती है, इसलिए अगर अभ्यास की कोई एक फाइल बदले तो उस पूरे अभ्यास के लिए एक्शन चलाना ज़्यादा सुरक्षित है।

जिन एक्शन को चलना चाहिए, उन्हें लोकल पर भी उपलब्ध कराना बहुत काम का हो सकता है। इसका मतलब है कि जो स्क्रिप्ट असली काम करती हैं, उन्हें हाथ से भी चलाया जा सके। इसके लिए वर्कफ्लो फाइलों के अंदर एक्शन को इनलाइन न करें, बल्कि एक अलग स्क्रिप्ट बनाइए। उदाहरण के लिए, स्टब की जाँच वर्कफ्लो फाइल के अंदर bash में पूरी तरह लिखी जा सकती है, लेकिन यहाँ सुझाव है कि इसके बजाय एक नई executable स्क्रिप्ट scripts/ci-check बनाई जाए।

"लेकिन कमांड तो बहुत छोटा है, जैसे eslint . --ext ts --ext tsx".

जब यह कमांड बदलनी पड़ती है, तो उसे डॉक्युमेंटेशन में हर जगह, वर्कफ्लो फाइलों में, और मेंटेनर के दिमाग में भी बदलना पड़ता है। इसे एक स्क्रिप्ट में निकाल देने से यह पूरी समस्या हल हो जाती है। वर्कफ्लो फाइल पढ़ना भी बहुत मुश्किल हो सकता है।

जिन PR में अभ्यास बदलते हैं, उनकी जाँच

scripts/pr और scripts/pr-check स्क्रिप्ट (टेम्पलेट देखिए) कई आर्गुमेंट के साथ चलाई जाती हैं, हर उस फाइल के लिए एक, जो इस PR में बदली या जोड़ी गई है। उदाहरण के लिए, अगर two-fer अपडेट हुआ है, तो कॉल कुछ ऐसा दिख सकता है:

scripts/pr exercises/two-fer/README.md exercises/two-fer/.meta/example.ext

किसी भी एक्शन को बदली गई फाइल पर नहीं, बल्कि बदले गए अभ्यास पर चलाने का सुझाव दिया जाता है। इसकी वजह यह है कि एक फाइल बदलने से पूरे अभ्यास में बदलाव हो सकते हैं (जैसे कॉन्फिगरेशन, पैकेज)।

अभी तैयार नहीं? / जटिल है?

इस ऑप्टिमाइज़ेशन को लागू करने से पहले इसे बेझिझक छोड़ा जा सकता है! माइग्रेशन गाइड में इसे बाद के किसी चरण में जोड़ने का संकेत है। अगर इनपुट आर्गुमेंट को नज़रअंदाज़ किया जाए, तो सभी जाँच सभी अभ्यासों पर चलेंगी। यह बिल्कुल ठीक है। बस इसमें ज़्यादा समय लगेगा।

अखंडता की जाँच

अगर ट्रैक में एक ही "टॉप-लेवल" डिपेंडेंसी फाइल और/या दूसरी कॉन्फिगरेशन फाइलें हैं, तो एक अखंडता स्टेप जोड़िए (जो scripts/sync या bin/sync के साथ रहता है, और जो सभी कॉन्फिगरेशन फाइलों को हर अभ्यास में कॉपी करता है)। यह स्टेप सुनिश्चित करता है कि टॉप-लेवल/बेस फाइलें वही हैं जो अभ्यास फोल्डरों में कॉपी की गई हैं। अब डिपेंडेंसी को अपडेट किया जा सकता है, पूरे रिपॉज़िटरी में सिंक किया जा सकता है, और हम यह सुनिश्चित कर सकते हैं कि सभी अभ्यासों में एक जैसा कॉन्फिगरेशन हो।

ऐसा करने का एक आम तरीका चेकसम का उपयोग करना है। Ubuntu (और कई दूसरे Linux डिस्ट्रीब्यूशन) के साथ sha1sum नाम का एक टूल आता है, लेकिन कॉन्फिगरेशन फाइल को हैश करके या घटाकर (md5, sha1, crc32) चेकसम वैल्यू बनाने का जो भी तरीका आप इस्तेमाल करें, वह काम करेगा:

$ sha1sum README.md
cd58091c5043bf21f00d39ff1740d8b2976deeff *README.md

सुरक्षा की जाँच

अगर ट्रैक ऐसे अतिरिक्त वर्कफ्लो इस्तेमाल करता है जिन्हें GitHub टोकन या दूसरे सीक्रेट तक पहुँच चाहिए, तो वर्कफ्लो में इस्तेमाल होने वाले सभी एक्शन को किसी एक खास कमिट पर पिन करना सबसे अच्छा तरीका है। जानकारी के लिए GitHub की सुरक्षा मज़बूत करने की गाइड देखिए।

उदाहरण के लिए:

- uses: julia-actions/setup-julia@v1
+ uses: julia-actions/setup-julia@d26d1111976eae5f00db04f0515ab744ec9cd79e # 1.3.1

अगर टूलिंग में डिपेंडेंसी मैनेजमेंट के लिए लॉकफाइल है, तो उसे रिपॉज़िटरी में चेक-इन करने पर विचार कीजिए और वर्कफ्लो फाइलों के अंदर "फ्रोज़न लॉकफाइल" इस्तेमाल कीजिए। उदाहरण के लिए: npm ci, yarn install --frozen-lockfile और bundle install --frozen। इससे यह सुनिश्चित होता है कि डिपेंडेंसी बदलते समय लॉकफाइल अप-टू-डेट रहे, और नुकसानदायक पैकेज अंदर आने से रुकते हैं।

टेम्पलेट

इस डायरेक्टरी में कम से कम ये टेम्पलेट हैं:

• configlet.yml: यह वर्कफ्लो नवीनतम configlet बाइनरी फेच करके इस रिपॉज़िटरी की लिंटिंग करेगा। हर कमिट पर चलता है। PR के लिए यह असली कमिट और "मर्ज के बाद" वाले ट्री पर चलता है।
• ci.yml: यह वर्कफ्लो सिर्फ main ब्रांच पर चलता है, हर कमिट पर एक बार।
  1. सभी अभ्यासों के लिए 'pre-check' कमांड चलाना (स्टब, लिंट, डॉक्स वगैरह की जाँच)
  2. सभी अभ्यासों के लिए कई वर्शन पर 'ci' कमांड चलाना (बिल्ड और परीक्षण)
• pr.ci.yml: यह वर्कफ्लो सिर्फ PR पर चलता है, हर कमिट पर एक बार।
  1. बदली हुई फाइलों के लिए 'pre-check' कमांड चलाना (स्टब, लिंट, डॉक्स वगैरह की जाँच)
  2. बदले हुए अभ्यासों के लिए कई वर्शन पर 'ci' कमांड चलाना (बिल्ड और परीक्षण)

गैर-PR वर्कफ्लो को workflow_dispatch के ज़रिए भी चलाया जा सकता है।

हर फाइल के ऊपर लिखा है कि कौन सी "स्क्रिप्ट" उपलब्ध होनी चाहिए। अगर आप इन्हें बाइनरी बनाना चाहते हैं, तो scripts/xxx की जगह bin/xxx लिखिए। कुछ टूलिंग के लिए बाइनरी का bin फोल्डर के अंदर होना ज़रूरी होता है।

• scripts/ci: ऐसी स्क्रिप्ट जो उदाहरण हल का उपयोग करके सभी अभ्यासों को टेस्ट के मुकाबले बिल्ड और परीक्षण करे
• scripts/ci-check: ऐसी स्क्रिप्ट जो सभी अभ्यासों की लिंटिंग करे, और चाहें तो स्टब, कॉन्फिगरेशन की अखंडता वगैरह की जाँच भी करे
• scripts/pr: scripts/ci जैसी ही, लेकिन इसे सिर्फ उन अभ्यासों पर चलना चाहिए जो इनपुट में दिए गए पाथ से निकलते हैं
• scripts/pr-check: scripts/ci-check जैसी ही, लेकिन इसे सिर्फ उन फाइलों या अभ्यासों पर चलना चाहिए जो इनपुट में दिए गए पाथ से निकलते हैं

समस्या निवारण

अगर आपको कोई दिक्कत आए या आप चाहें कि कोई आपके वर्कफ्लो की समीक्षा करे, तो कृपया @exercism/github-actions टीम को पिंग कीजिए।

टॉप-लेवल फाइल बदली, जिससे सभी अभ्यासों पर CI चलना चाहिए था

इस दस्तावेज़ को लिखते समय pr.ci.yml सिर्फ "एक्सटेंशन" के आधार पर टेस्ट की इजाज़त देता है। आदर्श रूप में इसे ऐसा अपडेट किया जाना चाहिए कि कुछ खास फाइलें बदलने पर यह हमेशा चले (जैसे टेस्ट चलाने वाली बाइनरी)। लेकिन ऐसे बदलाव अक्सर कम होते हैं और मेंटेनर करते हैं, इसलिए यह तथ्य कि ci.yml main पर हमेशा, हर चीज़ के लिए चलता है, शायद काफी सुरक्षित है।

Windows पर scripts/xxx फाइल बनाई और अब वह {दूसरे OS} पर काम नहीं करती

डिफ़ॉल्ट रूप से Windows पर बनी फाइलों के git-index में उनके executable होने के बारे में मेटाडेटा नहीं जुड़ता, क्योंकि Windows में परमिशन का ढंग अलग होता है। Git डिफ़ॉल्ट रूप से git-index के मेटाडेटा से तय करता है कि फाइल POSIX-आधारित सिस्टम पर executable होनी चाहिए या नहीं, और इस वजह से scripts/xxx फाइल executable नहीं होती।

git update-index --chmod=+x scripts/xxx
git commit -m "Make scripts/xxx executable"