Како постепено додавати валидациона правила и CI капије

Зашто је постепено увођење важно

Тимови често знају да им је потребна јача валидација, али направе једну од две грешке.

Или предуго остављају провере квалитета неформалним, или покушају да одједном уведу велики крут CI систем и тиме изазову фрустрацију.

Постепен приступ функционише боље.

Он омогућава пројекту да понављана очекивања из прегледа временом претвори у поновљиве провере.

Почните од понављаних грешака

Најбоља валидациона правила обично почињу као понављани налази у људским прегледима.

Питајте:

• које грешке се стално понављају
• која правила је лако заборавити
• која структура мора остати доследна кроз цео репозиторијум
• које провере квалитета би штеделе време особама које прегледају

Ако се исти проблем појави више пута, то је добар кандидат за аутоматизацију.

Валидација треба да прати ланац ауторитета

Валидациона правила треба да појачају документована очекивања, а не да их замене.

То значи:

• спецификација дефинише правило
• документација објашњава правило
• валидација проверава правило где је то практично
• CI доследно покреће валидацију

То спречава пројекат да спроводи правила о којима заправо никада није донета одлука.

Користан модел зрелости

Фаза 1: ручна контролна листа за преглед

Почните тако што ћете правило изричито именовати.

Примери:

• сав нови текст видљив кориснику мора бити локализабилан
• документација мора да раздваја тренутно стање од будућих планова
• нови јавни чланци морају да наводе спецификације и документацију, а не изворне фајлове

У овој фази правило је стварно, али га и даље спроводе људи.

Фаза 2: лагана локална валидација

Додајте малу скрипту или структурирану проверу коју сарадници могу да покрену локално.

Примери:

• откривање недостајућих кључева локализације
• провере присуства обавезних фајлова
• валидација генерисања метаподатака
• провере разрешавања линкова

Ова фаза смањује избегљиве грешке пре него што се CI уопште покрене.

Фаза 3: видљивост у CI-ју

Покрените проверу у CI-ју, чак и ако у почетку није блокирајућа.

То тиму даје увид у то колико често правило пада и да ли саму проверу треба дорадити.

Фаза 4: блокирајућа CI капија

Када је правило стабилно и разумљиво, учините га обавезним.

У том тренутку пројекат прелази са неформалног очекивања на спроводив стандард.

Шта прво аутоматизовати

Добри рани кандидати су обично:

• структурна доследност
• обавезни фајлови
• потпуност локализације
• исправност форматирања или синтаксе
• покварени интерни линкови
• забрањени уреднички наводи

За вишејезично објављивање третирајте кориснички видљив садржај на помешаним језицима као једну од првих CI капија високе вредности. Страница са локализованим насловом, али енглеским сажетком или енглеским ознакама није делимично успешна. Непотпуна је.

Ове провере су обично јефтине, објективне и веома корисне.

Шта не треба прерано наметати

Неке провере су вредне, али им можда треба време пре него што постану строге капије.

Примери:

• провера правописа на много језика
• провере снимака екрана или визуелних регресија
• провере приступачности док је подешавање још у току
• правила стила или формулације која још нису стабилна

Оне могу почети као саветодавни сигнали пре него што постану обавезне.

Примери из Let Books

Репозиторијум већ документује неколико образаца валидације, укључујући:

• основно тестирање локализације
• валидацију JSON синтаксе
• провере обавезних фајлова
• генерисање SEO метаподатака
• опциону проверу правописа и linting
• аутоматизацију објављивања

Документација и стилски водичи такође дефинишу уредничка правила која временом могу постати циљеви валидације, као што је коришћење спецификација и документације као канонских доказа за јавне чланке.

То Let Books чини добрим примером постепеног увођења уместо процеса све одједном.

Практичан ток претварања правила

Користите овај образац када додајете ново валидационо правило:

1. идентификујте понављани проблем у прегледима
2. јасно запишите правило у документацији или смерницама
3. додајте локалну скрипту или проверу ако је то практично
4. покрените је у CI-ју као видљиву повратну информацију
5. учините је блокирајућом тек када постане стабилна

То ствара мање трења него увођење строге капије пре него што тим разуме правило.

Питања која треба поставити пре додавања капије

1. Да ли је правило јасно документовано?
2. Да ли је провера довољно поуздана да јој се верује?
3. Да ли ће сарадници разумети како да исправе неуспехе?
4. Да ли вредност провере оправдава трење?
5. Да ли би требало да почне само као упозорење пре него што постане обавезна?

Пројектима уз помоћ AI ово је још потребније

AI повећава обим промена и брзину промене. То значи више прилика за недоследност.

Такође чини брзу повратну информацију вреднијом. Практично питање често није да ли AI може да произведе савршен први покушај. Корисније питање је да ли окружење може поуздано да препозна следећи проблем који треба решити.

Валидација и CI нису ту да успоре тимове. Ту су да спрече да брзина избрише важне границе.

У раду вођеном спецификацијама циљ није максимална аутоматизација. Циљ је поуздано појачавање правила која су најважнија.

Трајна лекција

Најјачи валидациони системи обично се не појављују потпуно формирани. Они расту тако што понављану људску процену претварају у документоване, прегледљиве и спроводиве провере.

Тај постепени пут је често најреалнији начин да пројекат постане строжи, а да не постане крхак.

Контролна листа за отклањање проблема из извора

Када валидационо правило падне:

1. прво прегледајте изворни Markdown
2. затим прегледајте локализоване метаподатке
3. прегледајте улазе за генерисање и регистре
4. поново генеришите артефакте
5. генерисани HTML прегледајте тек након провера на нивоу извора

Немојте поправљати генерисани излаз ако је изворна локализација непотпуна.

Даље читање

• ../spec-driven-content-program.md
• how-to-keep-spec-docs-demo-and-code-aligned.md
• how-to-review-ai-assisted-work-against-the-spec.md
• ../wiki/sr-Cyrl/spec-driven-development.md
• ../blog/sr-Cyrl/documentation-is-part-of-the-product.md