ГосКлюч

С чего начать?

Для быстрого старта на МосХаб мы подготовили список рекомендованных следующих шагов.

Вы профессионал? Тогда просто отредактируйте этот файл README.md так, как считаете нужным. Хотите сделать это еще легче? Используйте шаблон в конце данного документа!

Добавьте свои файлы в репозиторий

• Создайте или загрузите файлы
• Добавьте файлы посредством командной строки или сделайте пуш существующего репозитория Git при помощи следующих команд:

cd existing_repo
git remote add origin https://hub.mos.ru/comedyclub/external-apis/gos-key.git
git branch -M main
git push -uf origin main

Интегрируйте собственные инструменты

• Настройте интеграцию

Работайте совместно с командой

• Пригласите к участию участников команды или коллег
• Создайте новый запрос на слияние
• Автоматически закрывайте задачи при помощи запроса на слияние
• Включите согласование запросов на слияние
• Выполняйте автоматическое слияние веток при успешном завершении конвейера CI/CD

Отредактируйте этот файл README

Когда вы готовы сделать этот файл README своим, просто отредактируйте его и используйте удобный шаблон ниже (или сделайте все по-своему - это ведь отправная точка вашего проекта).

Предложения для написания хорошего файла README

Все проекты отличаются друг от друга, так что для начала решите, какие из разделов применимы к вашему проекту. Эти разделы используются в качестве шаблона для большинства проектов разработки ПО с открытым исходным кодом. Также примите во внимание, что слишком длинный и детальный README все же лучше, чем слишком короткий. Если ваш README вам кажется слишком длинным, рассмотрите иные способы документирования, не предполагающие сокращение детальности информации.

Название проекта

Выберите такое название проекта, которое говорит само за себя

Описание

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

Бейджи

В некоторых файлах README вы могли видеть маленькие значки, обозначающие разнообразные метаданные, такие как статус прохождения проектов различных тестов. Вы можете воспользоваться сервисом Shields для добавление некоторых подобных бейджей в ваш README. Многие другие сервисы, включая МосХаб, также предоставляют инструкции по добавлению бейджей.

Скриншоты

В зависимости от того, над чем вы работаете, хорошей идеей может быть включение в README скриншотов или даже видео (обычно в виде GIF-анимации). Инструменты наподобие ttygif могут вам в этом помочь.

Установка

В рамках конкретной экосистемы разработки могут существовать общеизвестные способы установки софта, такие как Yarn, NuGet или Homebrew. Тем не менее, примите во внимание возможность того, что читатель вашего README может быть новичком, которому могут потребоваться более подробные указания. Перечисление конкретных шагов поможет устранить неопределенность и побудить людей начать использование вашего проекта как можно скорее.

Если ваш проект работает только в специфическом контексте (например, только на конкретной версии языка программирования), или он требует ручной установки специфических зависимостей, рекомендуется добавить дополнительный подраздел "Требования"

Примеры использования

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

Поддержка

Объясните людям, где они могут получить техническую поддержку. Это может быть трекер задач, чат, адрес электронной почты и т.п.

Дорожная карта

Если у вас есть идеи для будущих релизов, их можно перечислить в данном разделе README.

Внести свой вклад

Если вы открыты ко вкладам сообщества, явно напишите об этом, а также перечислите требования, которые должны выполнить желающие внести свой вклад.

Для людей, которые хотят внести изменения в ваш проект, будет полезно иметь документацию о том, как им начать делать это. Возможно, им будет нужно запустить какой-либо скрипт или установить некие переменные окружения. Явно опишите требуемые шаги. Эти инструкции будут полезны вам самим в будущем.

Вы также можете внести в документ команды для запуска необходимых линтеров или тестов. Эти шаги помогут обеспечить высокое качество кода и уменьшить вероятность изменений, которые могут что-то непреднамеренно сломать. Инструкции по запуску тестов особенно полезны в случае, если для тестов требуются настройки сторонних инструментов, таких как сервер Selenium для тестирования веб-приложений.

Авторы и благодарности

Выразите свою благодарность тем, кто вносит вклад в ваш проект.

Лицензия

Для проектов с открытым исходным кодом необходимо указать лицензию, то есть явно написать о том, на каких условиях другие люди могут использовать ваш проект. Отсутствие информации о лицензии будет расцениваться как запрет легального использования вашего проекта. О видах лицензий можно прочитать тут.

Статус проекта

Если у вас не хватает сил или времени на ваш проект, сообщите об этом в начале файла README. Сообщите о том, что работа над проектом будет происходить медленно или будет совсем остановлена. Кто-нибудь может захотеть сделать форк вашего проекта, или найдется доброволец, готовый взять на себя роль сопровождающего вашего проекта, чтобы проект продолжал развиваться. Вы также можете явно написать о том, что ищете сопровождающего на ваш проект.