Како постепено да се додаваат правила за валидација и CI ограничувања

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

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

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

Постепениот пристап функционира подобро.

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

Почнете од повторливите грешки

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

Прашајте:

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

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

Валидацијата треба да го следи синџирот на авторитет

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

Тоа значи:

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

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

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

Фаза 1: рачна контролна листа

Почнете така што експлицитно ќе го именувате правилото.

Примери:

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

Во оваа фаза правилото е реално, но сè уште го спроведуваат луѓе.

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

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

Примери:

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

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

Фаза 3: видливост во CI

Извршете ја проверката во CI, дури и ако на почетокот не е блокирачка.

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

Фаза 4: блокирачко CI ограничување

Откако правилото ќе стане стабилно и разбрано, направете го задолжително.

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

Што прво да се автоматизира

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

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

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

Овие проверки обично се евтини, објективни и вредни.

Што не треба прерано да се наметнува

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

Примери:

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

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

Примери од Let Books

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

• основно тестирање на локализацијата
• валидација на JSON синтакса
• проверки за задолжителни датотеки
• генерирање SEO метаподатоци
• опционален spellcheck и 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/mk/spec-driven-development.md
• ../blog/mk/documentation-is-part-of-the-product.md