Заметки для разработчика который создаёт новый проект.
- Когда создаешь новый проект, старайся не использовать слово "service", потому что по сути они все сервисы и это мало как описывает его суть. Если не уверен как назвать, просоветуйся с тимлид-ом или девопс-ом
- Изначальный комит делай в ветке "dev", ветка "main" только для продакшена и если проект не готов к проду она вообще может быть пустой.
- Настрой ветку "dev" как ветку по умолчанию (default): Settings -> Repository -> Default branch
Readme должен содержать необхожимую для запуска информацию:
- Рабочий порт аппки
- Команда с которой аппка запускается из консоли, то что ты локально тестишь через IDE не имеет значения, так как мы делаем проекты под микросервисы, а там всё через консоль.
- Dependencies, если они есть, то есть что должно быть установлено в том "Линуксе" где предстоит запускать аппку для того чтобы она запустилась
- Требуемая версия окружения, например версия Java-ы или Python-a.
- Указать куда аппка подключается/с какими другими сервисами взаимодействую, кто подключается к ней, какими путями.
- Если есть переменные, должны быть перечислены с указанием их default значений или с примером значения
- Нужен ли публичный ip адрес
- Краткое описание принципа работы простыми словами.
- Если аппка нуждается в data persistency, то есть имеет файлы которые должны сохранятся между деплоями
- Если есть необхожимость в доступе на GCP, например в бакеты.
Написание краткой документации это естественная часть разработки, а не потеря времени как может показаться, время потраченное на это входит во время разработки.
Идеальная документация это та которая позволяет другому человеку запустить/задеплоить ваш проект не устраивая для этого получасовой допрос его разработчика. К этому по крайней мере нужно стремится.
Notes for the developer that creates a Gitlab project.
- Think of an explicit title for the project, avoid using words like "service", "project", "application", they don't really describe what is the project about, if you aren't sure how to name, discuss with your teamleader or with a devops.
- Make the initial commit to the "dev" branch, the "main" branch is only for production and should stay empty until the project is ready for production.
- Additionally, set the "dev" branch as default branch: Settings -> Repository -> Default branch
Project's README should contain the following information, where applicable:
- The port on which the app will run.
- The console command used for starting the app, the fact that you are testing it using IDE does not matter since we are developing apps as microservices for docker containers, you must know how to launch your app using terminal commands.
- Dependencies/Requirements aka what packages are required to be installed in that Linux environment where the app will work in order for it to function.
- The required version of software, ex: version of java, python, nodejs, etc.
- What is this app connecting to or how other apps are connecting to it, how do they interact.
- List the variables and their default values or with examples of values.
- Does it require a public ip address or the app is accessed only internally.
- Does it require data persistency, ex: it has a directory with files that should not be deleted between re-deploys, restarts, like a database would have.
- Doet it require access to GCP, ex: it need to access files from buckets.
If "something" is not required, simply don't mention it.
Use proper text formatting, you would need to read a bit about how gitlab markdown works.
The README must be easy to read and comprehend, a monolithic block of unformated text is "mission failed".