Software Engineering Metrics

Участие

Спасибо, что помогаете улучшать эту книгу. Приветствуется вклад любого размера, от исправления опечатки до написания новой темы.

Основные правила

Эта книга следует строгому фирменному стилю. Главное:

  • Никаких длинных тире. Используйте запятую, двоеточие, скобки или два предложения.
  • Никаких штампов («not only … but also», «load-bearing» и подобных).
  • Тёплая, простая, прямая проза. Обращайтесь к читателю прямо. Короткие предложения.
  • Определяйте термины при первом употреблении. Связывайте ключевые понятия с Википедией при первом упоминании.
  • Только настоящие источники.
  • Каждая тема семейства метрик называет путь манипулирования и страховочную метрику.

Полные правила находятся в spec/conventions.md в корне репозитория, а краткая версия это правила стиля. Механическую часть проверяют тесты.

Подготовка

Вам нужны Python 3 и just. Этот репозиторий хранит содержание и спецификацию книги, а также сайт на SvelteKit (software-engineering-metrics.github.io/), который превращает её в опубликованный веб-сайт.

just         # list tasks
just test    # run the validation suite
just nav     # regenerate the generated navigation files
just stats   # topic and word counts

Внесение изменения

  1. Прочитайте нужное руководство: создание тем для тем, навигация для сгенерированных файлов, тестирование для тестов.
  2. Сделайте самое маленькое изменение, которое решает задачу.
  3. Если вы добавляете, удаляете, переименовываете или перенумеровываете тему, обновите spec/structure.md в корне репозитория и запустите just nav.
  4. Запустите just test. Он должен пройти.
  5. Добавьте однострочную запись в журнал изменений в разделе Unreleased.

Над чем можно работать

  • Исправлять ошибки, неясные места или устаревшие источники.
  • Улучшать примеры, особенно конкретные примеры из предприятий и государственного сектора.
  • Сверять цитаты с настоящими источниками.
  • Заполнять пробелы в охвате темы, не ломая шаблон.

Чего избегать

  • Не правьте сгенерированные файлы (README.md, index.md каждой локали, front-matter/table-of-contents.md и topics/09-07-index.md) вручную. Меняйте темы и запускайте just nav.
  • Не правьте en-001, en-gb или en-us напрямую; они выводятся из en-gb-oxendict инструментом tools/localize.py.
  • Не добавляйте тему, не обновив также spec/structure.md.
  • Не вносите длинные тире или запрещённые выражения; тесты упадут.

Сообщения о проблемах

Откройте issue с описанием проблемы, файла и темы и, где уместно, верного источника или ссылки. Небольшие конкретные сообщения проще всего обрабатывать.