neuralgia/.github/CONTRIBUTING.md

Contribution to TerraFirmaGreg-Modern

Table of Contents

• Contribution to TerraFirmaGreg-Modern
  • Table of Contents
  • English Version
    • 1. Required and Recommended Software
      • Required Software
      • Recommended Software
    • 2. Project Preparation
      • Step 1: Cloning the Main Repository
      • Step 2: Creating a New Instance in PrismLauncher
      • Step 3: Cleaning the Project Folder
      • Step 4: Cloning the Repository into an Empty Folder
      • Step 5: Synchronizing Dependencies via Pakku
      • Step 6: Working with Branches and Creating Pull Request
      • Step 7: Processing and Merging Pull Request
    • 3. Additional Recommendations
  • Russian Version
    • 1. Необходимое и рекомендуемое ПО
      • Необходимое ПО
      • Рекомендуемое ПО
    • 2. Подготовка проекта
      • Шаг 1: Клонирование основного репозитория
      • Шаг 2: Создание новой инстанции в PrismLauncher
      • Шаг 3: Очистка папки проекта
      • Шаг 4: Клонирование репозитория в пустую папку
      • Шаг 5: Синхронизация зависимостей через Pakku
      • Шаг 6: Работа с ветками и создание Pull Request
      • Шаг 7: Обработка и вливание Pull Request
    • 3. Дополнительные рекомендации

---

English Version

1. Required and Recommended Software

Required Software

• Git: A version control system for managing source code.
• Pakku: A tool for dependency management and modpack building.

Warning

Ensure that Java version 17 is installed on your machine, as it is required for Forge and Pakku to function properly.

Recommended Software

• PrismLauncher: An optimized launcher for Minecraft modifications, making it easier to create separate instances.
• Visual Studio Code: A code editor with extensive capabilities for working with projects and integrating various plugins.
• GitHub Desktop: A graphical client for managing Git repositories developed by GitHub.

---

2. Project Preparation

Step 1: Cloning the Main Repository

1. Go to the official repository page of TerraFirmaGreg-Modern on GitHub.

2. Clone the repository using one of the following methods:

   Method A: GitHub Desktop

   • Open GitHub Desktop and log in.
   • Select File → Clone repository...
   • Go to the URL tab and enter:

     https://github.com/TerraFirmaGreg-Team/Modpack-Modern.git
     

   • In the Local Path field, select or create a folder for the repository, e.g., TerraFirmaGreg-Modern/minecraft.
   • Click Clone.

   Method B: Terminal / cmd

   • Open terminal or cmd in the desired directory.
   • Execute the command:

     git clone https://github.com/TerraFirmaGreg-Team/Modpack-Modern.git "PATH_TO_FOLDER/TerraFirmaGreg-Modern/minecraft"
     

   • Replace PATH_TO_FOLDER with the appropriate path in your environment.

Tip

This approach allows you to immediately work with the main version of the repository for local testing and development.

Step 2: Creating a New Instance in PrismLauncher

1. Open PrismLauncher and click on the Add Instance button.
2. In the Name field, enter the name TerraFirmaGreg-Modern.
3. Select Minecraft version 1.20.1 and Forge version 47.4.6 — these versions are necessary for the modpack to work correctly.

Tip

Step 3: Cleaning the Project Folder

1. Locate the instance folder in the PrismLauncher directory at TerraFirmaGreg-Modern/minecraft.

Tip

For quick access, right-click on the instance and select Folder.

Warning

Delete all files and directories inside the minecraft folder to avoid version conflicts and leftover old data.

Step 4: Cloning the Repository into an Empty Folder

If you did not clone the repository in Step 1, follow these steps:

Method A: GitHub Desktop

1. Open GitHub Desktop and log in.
2. Select File → Clone repository...
3. On the URL tab, enter: https://github.com/TerraFirmaGreg-Team/Modpack-Modern.git
4. In the Local Path field, select the TerraFirmaGreg-Modern/minecraft folder created in Step 2.
5. Click Clone.

Method B: Terminal / cmd

1. Open terminal or cmd in the root directory of the TerraFirmaGreg-Modern folder.
2. Execute the command:

 git clone https://github.com/TerraFirmaGreg-Team/Modpack-Modern.git "minecraft"

This command creates a minecraft folder inside TerraFirmaGreg-Modern and downloads the repository files there.

Tip

This approach allows you to work with the main version of the repository for local testing and development.

Step 5: Synchronizing Dependencies via Pakku

1. Open terminal or cmd in the root directory of the TerraFirmaGreg-Modern/minecraft folder.
2. Execute the following command:

  pakku fetch

Tip

This command downloads all necessary project files into the modpacks folder. Note that the command may differ depending on how Pakku was installed.

Step 6: Working with Branches and Creating Pull Request

There are two approaches to creating a Pull Request: via terminal and via GitHub Desktop.

Branch Designation

• main:

  • This branch contains the stable, tested, and released version of the project.
  • It should only contain changes that have passed the full review cycle.
  • Changes can be accepted by members of the Dev-Modern team; at least one approval is required.

• dev:

  • The main development branch where new features, bug fixes, and experimental changes are integrated.
  • After testing, changes from dev may be merged into the main branch for a new version release.
  • Changes can be accepted by members of the Contributor-Modern team; at least two approvals are required.

• feature/bugfix-branch:

  • For example, (feature/add-custom-quest) or (bugfix/fix-launch-crash).
  • It is recommended to create separate branches from dev for developing specific features or fixing bugs.
  • After completing the work, merge them back into dev.
  • Members of the Contributor-Modern team can create branches in the main repository.

Process of Creating Pull Request

Method A: GitHub Desktop

1. Creating a New Branch:

   • Open GitHub Desktop and ensure that your local repository TerraFirmaGreg-Modern is selected.
   • In the top menu, select Branch → New Branch....
   • In the appearing window, enter a name for your new branch (e.g., feature/add-custom-quest or bugfix/fix-launch-crash).
   • Click Create Branch. Now you are in a new branch created from the dev branch.

2. Making and Committing Changes:

   • Make the necessary changes to the project using your favorite code editor (e.g., Visual Studio Code).
   • Return to GitHub Desktop, go to the Changes tab, where you will see a list of modified files.
   • Add a description of your changes, enter a commit message, and click Commit to <branch_name>.

3. Publishing the Branch:

   • After committing changes, click the Push origin button in the top right corner of GitHub Desktop.
   • This will send your new branch to GitHub.

4. Creating Pull Request:

   • After a successful push, GitHub Desktop will offer you a Create Pull Request button or a link View on GitHub. Click it.
   • In the opened web interface of GitHub, ensure that:
     • The base branch for merging is set to dev of the main repository.
     • The title and description of the Pull Request contain detailed descriptions of the changes made, as well as links to related Issues if necessary.
   • Click Create Pull Request to send a request to merge your changes into the dev branch.

Method B: Using terminal / cmd

1. Synchronizing with upstream:

• Ensure that your local repository is up-to-date. If you have already set up remote upstream (the official repository), execute:

  git checkout dev
  git pull upstream dev

2. Creating a new branch for changes:

• From the dev branch, create a new feature or bugfix branch:

git checkout -b feature/name-of-feature

• Name your branch clearly (e.g., feature/add-custom-quest or bugfix/fix-crash-on-launch).

3. Making changes:

• Make changes to the code, accompanied by commits with clear messages:

git add .
git commit -m "Brief description of changes made"

4. Pushing the branch to GitHub:

• Push your branch to your fork:

git push origin feature/name-of-feature

5. Creating Pull Request:

• Go to the page of your fork on GitHub.
• Click the Compare & Pull Request button next to the just pushed branch.
• Ensure that dev of the main repository is selected as the base branch.
• Fill in the title and description of the Pull Request, mention which problems this PR solves, and if possible, provide links to corresponding Issues.
• Send the request by clicking Create Pull Request.

Tip

If you have questions about formatting a Pull Request or are unsure with which branch to merge, refer to the project documentation or contact the team via Discord.

Step 7: Processing and Merging Pull Request

1. Reviewing Pull Request:

• After creating a Pull Request, it enters a queue for review by members of the team.
• Members of Dev-Modern (for merging into main) or Contributor-Modern (for merging into dev) review the changes made, leave comments, and request revisions if necessary.

2. Making Corrections:

• If corrections are required, the PR author makes them in their branch, and the updated commit automatically appears in the open request.

3. Approval:

• After making all necessary corrections and receiving positive feedback from reviewers, the PR is considered approved.
• To merge changes into main, at least one approval from members of the Dev-Modern team is required.
• For merging into dev – at least two approvals from members of the Contributor-Modern team are required.

4. Merging Pull Request:

• After approval, an authorized member or maintainer performs the merge PR (using Squash and Merge according to project rules).
• After successful merging, it is recommended to delete the branch to maintain repository cleanliness.

5. Post-Merge:

• The merge of PR triggers build and testing processes to ensure the stability of the changes made.
• If issues are discovered after merging, a new Pull Request is created for their resolution.

---

3. Additional Recommendations

• Semantic Versioning Rules:

  • The project follows Semantic Versioning.
  • Patch: Bug fixes and small changes (1.0.0 → 1.0.1)
  • Minor: New features that don't break compatibility (1.0.0 → 1.1.0)
  • Major: Breaking changes (1.0.0 → 2.0.0)

• Working with Git:

  • Create separate branches for each new functionality or bug fix.
  • Regularly synchronize your fork with the original repository to avoid conflicts.
  • Use clear commit messages for better understanding of changes.

• Debugging and Testing:

  • Before making your changes, ensure that the project runs without errors.
  • Check PrismLauncher logs to identify potential issues.
  • Using Visual Studio Code with the ProbeJs extension helps quickly detect and fix errors.

• Documentation and Discussion:

  • If you have questions or problems, refer to the Issues or Discussions section of the GitHub project, as well as forums on Discord.
  • Collective discussion often leads to finding optimal solutions and improving the project overall.

• Collaborative Development:

  • Always test the integration of your changes with the main project.
  • Before sending a Pull Request, it is important to ensure that your changes do not disrupt the modpack's operation and comply with internal code of conduct.

• Localization:

  • If you're looking for Localizing the modpack to a Language, please feel free to head to the Tools-Modern

• Linting & Typescript support

  • Install NodeJS and use an editor with Typescript and ESLint support (e.g. Visual Studio Code).
  • Run npm init, and create a project with default options. (required for language support to work properly)
  • Run npm install --save-dev eslint@latest @eslint/js@latest @stylistic/eslint-plugin
  • To enable type annotations & diagnostics, run ProbeJS and set noCheck: false in tsconfig.json.

---

Russian Version

1. Необходимое и рекомендуемое ПО

Необходимое ПО

• Git: Система контроля версий для управления исходным кодом.
• Pakku: Инструмент для управления зависимостями и сборкой модпака.

Warning

Убедитесь, что на вашей машине установлена 17 версия Java, необходимая для работы Forge и Pakku.

Рекомендуемое ПО

• PrismLauncher: Лаунчер, оптимизированный для работы с модификациями Minecraft, облегчающий создание отдельных инстанций.
• Visual Studio Code: Редактор кода с широкими возможностями для работы с проектами и интеграции различных плагинов.
• GitHub Desktop: Графический клиент для управления Git-репозиториями, разработанный компанией GitHub.

---

2. Подготовка проекта

Шаг 1: Клонирование основного репозитория

1. Перейдите на страницу официального репозитория TerraFirmaGreg-Modern на GitHub.

2. Склонируйте репозиторий, используя один из следующих способов:

   Способ A: GitHub Desktop

   • Откройте GitHub Desktop и авторизуйтесь.
   • Выберите File → Clone repository...
   • Перейдите на вкладку URL и введите:

     https://github.com/TerraFirmaGreg-Team/Modpack-Modern.git
     

   • В поле Local Path выберите или создайте папку для репозитория, например, TerraFirmaGreg-Modern/minecraft.
   • Нажмите Clone.

   Способ B: Terminal / cmd

   • Откройте terminal или cmd в нужной директории.
   • Выполните команду:

     git clone https://github.com/TerraFirmaGreg-Team/Modpack-Modern.git "ПУТЬ_ДО_ПАПКИ/TerraFirmaGreg-Modern/minecraft"
     

   • Замените ПУТЬ_ДО_ПАПКИ на нужный путь в вашем окружении.

Tip

Такой подход позволяет сразу работать с основной версией репозитория для тестирования и разработки локально.

Шаг 2: Создание новой инстанции в PrismLauncher

1. Откройте PrismLauncher и нажмите на кнопку Add Instance.
2. В поле Name введите название TerraFirmaGreg-Modern.
3. Выберите версию Minecraft 1.20.1 и версию Forge 47.4.6 — именно эти версии необходимы для корректной работы модпака.

Tip

Шаг 3: Очистка папки проекта

1. Найдите папку инстанции в директории PrismLauncher по пути TerraFirmaGreg-Modern/minecraft.

Tip

Для быстрого доступа нажмите правой кнопкой по инстанции и выберите Folder.

Warning

Удалите все файлы и каталоги внутри папки minecraft, чтобы избежать конфликтов версий и остатков старых данных.

Шаг 4: Клонирование репозитория в пустую папку

Если вы не клонировали репозиторий на шаге 1, выполните следующие действия:

Способ A: GitHub Desktop

1. Откройте GitHub Desktop и авторизуйтесь.
2. Выберите File → Clone repository...
3. На вкладке URL введите: https://github.com/TerraFirmaGreg-Team/Modpack-Modern.git
4. В поле Local Path выберите папку TerraFirmaGreg-Modern/minecraft, созданную на Шаге 2.
5. Нажмите Clone.

Способ B: Terminal / cmd

1. Откройте terminal или cmd в корневой директории папки TerraFirmaGreg-Modern.
2. Выполните команду:

 git clone https://github.com/TerraFirmaGreg-Team/Modpack-Modern.git "minecraft"

Эта команда создаст папку minecraft внутри TerraFirmaGreg-Modern и скачает туда файлы из репозитория.

Tip

Такой подход позволяет работать с основной версией репозитория для тестирования и разработки локально.

Шаг 5: Синхронизация зависимостей через Pakku

1. Откройте terminal или cmd в корневой директории папки TerraFirmaGreg-Modern/minecraft.
2. Выполните следующую команду:

  pakku fetch

Tip

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

Шаг 6: Работа с ветками и создание Pull Request

Есть два подхода для создания Pull Request: через терминал и через GitHub Desktop.

Назначение веток

• main:

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

• dev:

  • Основная ветка для разработки. Здесь интегрируются новые функции, исправления ошибок и экспериментальные изменения.
  • После тестирования изменения из dev могут быть перенесены в ветку main для выпуска новой версии.
  • Принимать изменения могут участники команды Contributor-Modern, требуется одобрение хотя бы двух.

• feature/bugfix-branch:

  • Например, (feature/add-custom-quest) или (bugfix/fix-launch-crash).
  • Рекомендуется создавать отдельные ветки от dev для разработки конкретных функций или исправления ошибок.
  • После завершения работы их следует слить обратно в dev.
  • Создавать ветки в основном репозитории могут все участники команды Contributor-Modern.

Процесс создания Pull Request

Способ A: GitHub Desktop

1. Создание новой ветки:

   • Откройте GitHub Desktop и убедитесь, что выбран ваш локальный репозиторий TerraFirmaGreg-Modern.
   • В верхнем меню выберите Branch → New Branch....
   • В появившемся окне введите имя для вашей новой ветки (например, feature/add-custom-quest или bugfix/fix-launch-crash).
   • Нажмите Create Branch. Теперь вы находитесь в новой ветке, созданной от ветки dev.

2. Внесение и фиксация изменений:

   • Внесите нужные изменения в проекте через ваш любимый редактор кода (например, Visual Studio Code).
   • Вернувшись в GitHub Desktop, перейдите на вкладку Changes, где вы увидите список изменённых файлов.
   • Добавьте описание своих изменений, введите сообщение коммита и нажмите Commit to <имя_ветки>.

3. Публикация ветки:

   • После фиксации изменений нажмите кнопку Push origin в правом верхнем углу GitHub Desktop.
   • Это отправит вашу новую ветку на GitHub.

4. Создание Pull Request:

   • После успешного пуша GitHub Desktop предложит вам кнопку Create Pull Request или ссылку View on GitHub. Нажмите её.
   • В открывшемся веб-интерфейсе GitHub убедитесь, что:
     • Базовая ветка для слияния установлена как dev основного репозитория.
     • Заголовок и описание Pull Request содержат подробное описание вносимых изменений, а также при необходимости ссылки на связанные Issues.
   • Нажмите Create Pull Request для отправки запроса на слияние ваших изменений в ветку dev.

Способ B: Использование terminal / cmd

1. Синхронизация с upstream:

• Убедитесь, что ваш локальный репозиторий актуален. Если вы уже настроили remote upstream (официальный репозиторий), выполните:

  git checkout dev
  git pull upstream dev

2. Создание новой ветки для изменений:

• Из ветки dev создайте новую feature или bugfix ветку:

git checkout -b feature/имя-фичи

• Назовите ветку так, чтобы было ясно, что в ней содержится (например, feature/add-custom-quest или bugfix/fix-crash-on-launch).

3. Внесение изменений:

• Делайте изменения в коде, сопровождая их коммитами с понятными сообщениями:

git add .
git commit -m "Краткое описание внесённых изменений"

4. Отправка ветки на GitHub:

• Запушьте свою ветку в свой форк:

git push origin feature/имя-фичи

5. Создание Pull Request:

• Перейдите на страницу вашего форка на GitHub.
• Нажмите кнопку Compare & Pull Request напротив только что запушенной ветки.
• Убедитесь, что в качестве базовой ветки выбран dev основного репозитория.
• Заполните заголовок и описание Pull Request, упомяните, какие проблемы решает данный PR, и, если возможно, укажите ссылки на соответствующие Issues.
• Отправьте запрос, нажав Create Pull Request.

Tip

Если у вас возникнут вопросы по оформлению Pull Request или вы не уверены, с какой веткой проводить слияние, обратитесь к документации проекта или свяжитесь с командой через Discord.

Шаг 7: Обработка и вливание Pull Request

1. Рассмотрение Pull Request:

• После создания Pull Request он попадает в очередь на рассмотрение членами команды.
• Участники Dev-Modern (для слияния в main) или Contributor-Modern (для слияния в dev) просматривают внесённые изменения, оставляют комментарии и, при необходимости, запрашивают доработки.

2. Внесение корректировок:

• Если требуются изменения, автор PR вносит корректировки в свою ветку, и обновлённый коммит автоматически появляется в открытом запросе.

3. Одобрение:

• После внесения всех необходимых правок и получения положительных отзывов от рецензентов PR считается одобренным.
• Для слияния изменений в main требуется минимум одно одобрение от участников команды Dev-Modern.
• Для слияния в dev – минимум два одобрения от участников команды Contributor-Modern.

4. Слияние Pull Request:

• После одобрения уполномоченный участник или мейнтейнер выполняет слияние PR (при помощи Squash and Merge, согласно правилам проекта).
• После успешного слияния рекомендуется удалить ветку, чтобы поддерживать чистоту репозитория.

5. Пост-слияние:

• Слияние PR запускает процессы сборки и тестирования, чтобы убедиться в стабильности внесённых изменений.
• Если после слияния обнаружены проблемы, создаётся новый Pull Request для их исправления.

---

3. Дополнительные рекомендации

• Правила семантического версионирования:

  • The project follows Semantic Versioning.
  • Patch: Исправлены ошибки и небольшие изменения (1.0.0 → 1.0.1)
  • Minor: Новые функции, которые не нарушают совместимость (1.0.0 → 1.1.0)
  • Major: Критические изменения (1.0.0 → 2.0.0)

• Работа с Git:

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

• Отладка и тестирование:

  • Перед внесением ваших изменений убедитесь, что проект запускается без ошибок.
  • Проверяйте логи PrismLauncher для выявления возможных проблем.
  • Использование Visual Studio Code с расширением ProbeJs поможет быстрее обнаруживать и устранять ошибки.

• Документация и обсуждение:

  • Если у вас возникли вопросы или проблемы, обратитесь к разделу Issues или Discussions на GitHub проекта, а так же форумах Discord.
  • Коллективное обсуждение часто приводит к нахождению оптимальных решений и улучшению проекта в целом.

• Совместная разработка:

  • Всегда тестируйте интеграцию ваших изменений с основным проектом.
  • Перед отправкой Pull Request важно убедиться, что ваши изменения не нарушают работу модпака и соответствуют внутренним соглашениям по коду.

• Локализация:

  • Если вы ищете локализацию Modpack на языке, пожалуйста, не стесняйтесь перейти к Tools-Modern

---