Skip to content

Contributing

Jump to bottom
Fabrizio La Rosa edited this page Mar 10, 2025 · 3 revisions

How to Contribute

Educator Tools is an open-source project, and we welcome contributions from educators, developers, and Minecraft enthusiasts. Whether you want to improve existing features, fix bugs, or propose new ideas, your input helps shape the future of this toolset.

1. Prerequisites

Before you begin, make sure you have installed the following:

  • Git or GitHub Desktop
    Git is essential for cloning the repository and managing version control. If you prefer a graphical interface, install GitHub Desktop. Otherwise, download Git from git-scm.com.

  • Python 3.13
    Download it directly from the official Python website. Note: Do NOT use the version available from the Windows Store.

  • NodeJS LTS
    Install the Long Term Support version from the official NodeJS website. This will be used for managing our TypeScript modules and dependencies.

  • Regolith
    Our project uses Regolith (from Bedrock-Oss) as a compiler for our files. Follow the installation instructions available in Regolith’s official documentation.

  • Minecraft Education You need Minecraft Education installed from the Windows Installer in order for Regolith to compile correctly.

2. Cloning the Repository

Before cloning, you need to fork the repository so that you have your own copy to work on.

2.1. Forking the Repository

  1. Visit the Repository on GitHub:
    Open the repository page in your web browser.

  2. Click the Fork Button:
    In the top right corner of the page, click the "Fork" button. This will create a copy of the repository under your GitHub account.

2.2. Cloning Your Fork

Once you have forked the repository, you can clone it to your local machine using either Git (command line) or GitHub Desktop.

Using Git (Command Line)

  1. Open your terminal or command prompt.
  2. Clone your forked repository:
    Replace <your-fork-URL> with the URL of your fork: 
    git clone https://github.com/ShapescapeMC/Educator-Tools.git
  3. Navigate to the project folder: 
    cd Educator-Tools

Using GitHub Desktop

  1. Download and install GitHub Desktop from desktop.github.com if you haven't already.
  2. Open GitHub Desktop and sign in with your GitHub account.
  3. Clone your forked repository:
    • Click on "File" in the menu and select "Clone Repository...".
    • In the dialog that appears, select the "URL" tab, then paste your fork's URL.
    • Choose the local path where you want the repository to be saved.
    • Click "Clone" to download the repository to your computer.

3. Installing Dependencies

There are multiple steps to install the necessary dependencies.

3.1. NodeJS Dependencies

The project uses Node to manage TypeScript modules. The package_lock.json file is located in the ./regolith/filters_data folder and lists the necessary dependencies. To install them manually:

  1. Open the terminal in the ./regolith/filters_data directory: 
    cd regolith/filters_data
  2. Run the following command: 
    npm install
    This command will install all the dependencies listed in the package_lock.json file.

3.2. Regolith Dependencies

In addition to the NodeJS dependencies, you must also run the following command in the regolith folder to install Regolith-specific dependencies:

  1. Open the terminal in the regolith directory: 
    cd regolith
  2. Execute the command: 
    regolith install-all
    Note: If you encounter errors during this process, running the command again may resolve them.

3.3. Using the Provided PowerShell Script

There is also a PowerShell script available to install dependencies:

  • Script Location:
    The script is located in the scripts folder and is named install_dependencies.ps1.

  • Running the Script:
    You can execute this script directly from your terminal or run it as a task in VSCode.
    From the terminal, navigate to the scripts folder:

    cd .scripts

    Then run:

    .\install_dependencies.ps1

By following these steps, you'll have all the necessary dependencies installed for both NodeJS and Regolith.

4. Modifying the Code

Our project uses the system_template filter by Nusiq for modular code development, allowing flexible and reusable code components. Follow these steps to modify the code:

  1. Locate the Source Files:
    The source files are primarily located in the Regolith-related directories, particularly in ./regolith/filters_data/system_template/. Additionally, a manifest.json file in the scripting_setup folder contains references to the Minecraft modules.

  2. Make Your Changes:

    • Open the files in your preferred text editor or IDE.
    • Apply your modifications while following best coding practices. Include comments as necessary.
    • For changes in TypeScript files, remember that NodeJS manages these modules; you may need to recompile the project to see your changes.

  3. Test Your Changes Locally:
    After modifying the code, ensure that the project runs as expected.

  4. Commit and Push Your Changes:
    Once you’ve verified your changes, use the following commands:

    git add .
git commit -m "Description of changes made"
git push origin main

Adding a Translation

If you want to add a translation to the project, follow these steps:

  1. Navigate to the directory regolith\filters_data\system_template\educator_tools\ui\translations.
  2. Copy the file en_US.lang and rename the copy to match the locale of the language you wish to translate (for example, it_IT.lang for Italian or fr_FR.lang for French).
  3. Open the new language file and translate the contents accordingly.
  4. Save your changes and commit the new translation file to the repository.

5. Building the Project / Running Regolith

There are two equivalent methods to build the project and compile your files: using the build.ps1 script or running the regolith run command directly. You can use either method according to your preference.

5.1. Using the Build Script

  • Script Location:
    The build script is located in the .scripts folder and is named build.ps1.

  • Running the Script:
    You can execute this script directly from your terminal or as a task in VSCode.
    To run from the terminal:

    1. Navigate to the scripts folder: 
      cd .scripts
    2. Execute the build script: 
      .\build.ps1

5.2. Using Regolith Directly

Alternatively, you can use the Regolith command:

  1. Navigate to the Regolith Folder:
    Open your terminal and move to the regolith directory: 
    cd regolith
  2. Run Regolith:
    Execute the following command: 
    regolith run

Both methods achieve the same result, such as compiling your files for Minecraft Bedrock.

6. Creating a Pull Request

After pushing your changes to your fork, follow these steps to open a Pull Request (PR) and contribute your work to the original repository:

  1. Push Your Changes:
    Please ensure you have committed your changes locally and pushed them to your fork on GitHub.

  2. Open Your Fork on GitHub:
    Navigate to your forked repository on GitHub in your web browser.

  3. Initiate the Pull Request:

    • GitHub often shows a prompt to "Compare & pull request" after you push new commits. Click this button, or click on the "Pull Requests" tab and then "New Pull Request."
    • Make sure you are comparing your branch (with your changes) against the original repository’s main branch (or the appropriate target branch).

  4. Fill in the PR Details:

    • Title: Provide a clear, concise title that summarizes your changes.
    • Description: Include a detailed description of the changes, why they were made, and any additional context. If the repository has a PR template, follow the provided structure.
    • Link Issues: If your changes address specific issues, reference them (e.g., "Fixes #123").

  5. Submit the PR:
    Once you’re satisfied with the details, click "Create Pull Request" to submit it for review.

7. Final Tips

  • Read the Documentation:
    Review the official Regolith and System Template documentation to stay updated on any changes or specific details.

  • Set Up a Development Environment:
    Use an IDE like Visual Studio Code that supports debugging and syntax highlighting to streamline your development process.

Clone this wiki locally