Be more newcomer/dev-friendly

[nilsonragee]

Кратко:

1. Сделать общий overview всего проекта с подробным описанием всех компонентов и как они взаимодействуют. Тут можно или на каждый модуль txt/MD файл расписать, либо какой-нибудь мега канвас в Milton нарисовать (но только аккуратный), либо сделать один большой стрим-обзор и потом оставить на него ссылку.
2. Оставлять побольше, а главное детальных комментариев. Это конечно же не значит, что под каждый строчкой нужно комментарий, но лучше не стесняться описать какой-то спорный момент или в общем написать что стремится сделать чанк кода.

Подробно:

Думаю ни для кого не секрет, что по большей части проектом занимаются трудолюбивые товарищи provod и NightFox, которые уже несколько лет ведут этот проект за собой, за что им респект и уважение (всем, кто помогал, разумеется тоже). Но проект еще не закончен, и перспектива к первому пред-альфа/альфа прототипу видется только через год, из чего можно сделать вывод - лишние руки не помешают (а очень даже помогут).

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

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

А теперь к сути проблемы - новичкам очень тяжело вкатиться. Я попробовал сам и ощутил это на своей шкуре. Начал с самого простого, что смог найти - задачка с тегом good-first-issue и код почти минимальной сложности - сделать дебаг принт менее громоздким и более читаемым. Пришлось посидеть, дня 2 так точно, чтобы просто вникнуть в проект, разобраться с базовой архитектурой, что куда. Но это ожидаемо - кодовую базу ни разу не видел, сидел и читал каждый файлик, хотя, конечно, участок кода был практически самостоятельным и никуда, кроме консоли, обращаться не надо было.

Сейчас я уже работаю над вторым PR-ом, который тянется довольно долго. Естественно, по большей части я просто сам отсутствовал, но все же - недопонимания есть, каждый код-ревью что-то отмечается на исправление, возникают какие-то вопросы и т.д. И спасибо огромное проводу, что находит время на это, т.к., как я понимаю, все свободное время и так уходит на халву - по 3-4 часа стримов в день, в которых все и происходит.

И даже, казалось бы, уже посидев над код базой приличное время и, вроде как, приспособившись, может показаться, что я достаточно опытен и имею картину того, что происходит. Но... нет. Я представляю себе разве что очень простую, общую картину - у нас есть движок, мы являемся отдельной динамической графической библиотекой, нас грузит движок и мы для него рисуем. Порог входа очень высокий, и даже мои, казалось бы, хоть какие-то базовые знания по OpenGL с туториалов learnopengl и немножко Vulkan с туториалов первого треугольника - кажутся пустым местом.

Лить воду дальше не буду, а то и так уже налил - до сих пор не знаю, что за sebastian.py, кто такой meatpipe и rt.meat и т.д. Это прям мои основные черные ящики, но и с других компонентов наберется вопросов. Отсюда прям назревает вопрос - где документация, емае? Вот бы было, как в Vulkan спеке, просто берешь, открываешь, и там все написано! Ладно, шутка, естественно такого здесь не будет, но хоть какой-то гайд по тому что и как работает нужно организовать, потому что удержать все это в голове невозможно, так еще и со временем улетучивается.

Фух, поныл от души... Поэма окончена, все предложения сверху :)

[0x4E69676874466F78]

Ну маленькие шажки в эту сторону идут, из недавнего https://github.com/w23/xash3d-fwgs/blob/vulkan/CONTRIBUTING.md

[ils8]

also you need mods for toxic/condescending ppl

[ils8]

https://discord.com/channels/705836771304538152/1185430942609850419/1185431156720668713

[0x4E69676874466F78]

@nilsoncore

Оставлять побольше, а главное детальных комментариев.

Кстати если вдруг не видел, то есть вот такие файлы:
https://github.com/w23/xash3d-fwgs/blob/vulkan/ref/vk/NOTES.md
https://github.com/w23/xash3d-fwgs/blob/vulkan/ref/vk/TODO.md

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

[ils8]

The closely knitted community does not allow for easy integration of newcomers, if they are not ready to become wordless carpets of the bourgeoisie for the first five or so commits

[0x4E69676874466F78]

The closely knitted community does not allow for easy integration of newcomers, if they are not ready to become wordless carpets of the bourgeoisie for the first five or so commits

Ты опять выходишь на связь?

[ils8]

The closely knitted community does not allow for easy integration of newcomers, if they are not ready to become wordless carpets of the bourgeoisie for the first five or so commits

Ты опять выходишь на связь?

Хм, а ты даже читать разучился, что переспрашиваешь очевидные вещи?

[ils8]

The closely knitted community does not allow for easy integration of newcomers, if they are not ready to become wordless carpets of the bourgeoisie for the first five or so commits

Ты опять выходишь на связь?

Хм, а ты даже читать разучился, что переспрашиваешь очевидные вещи?

Why do those super egotistic members of the community only understand an argument if its delivered with the standpoint of maximum rudeness and overpowering discrimination? Weird doomer mentality.