Repository navigation
Github Basics
This is an in depth guide, meant for contributors to the project which are not familiar with Git(hub). When in doubt or in need of help, ask in Discord for assistance! We're a team, and we're always prepared to help each other!
If you do not have a Github account, or aren't added in a Github team, then contact Lithrun on Discord to add you.
Github is a version control system, which allows all contributors of AoTTG 2 to effectively collaborate and develop new features without having to worry about ruining other peoples work. Everything you release on the server, is logged by the version control. Everything can be undone, and no history can be deleted.
An issue within Github is a task that one or multiple people can work on. An issue has one or multiple labels. With labels we can structure all the issues we have. Keep track of their state, priority and to which team(s) the issue belongs. You can only work on an issue that is assigned to your team, and only one person can work at an issue at a time. If you want to help someone on their issue, you must contact the person to avoid merge conflicts. If there's no issues available for your team, then please contact your team leader to discuss how else you can contribute.
Within Github, we have the following protected branches:
- Master (Not yet available) - The master branch contains a stable and tested version of AoTTG 2. Everything that is accepted onto master will be included in the next release / update for AoTTG 2.
- Release Candidate (Not yet available) - Release candidate is a candidate version of AoTTG 2. Once the development branch is ready, then it will be synced with Release Candidate. Testing team will then actively test the Release Candidate. If it gets accepted, then the changes of Release Candidate get moved into master. Otherwise additional changes are required, and a new version is moved into Release Candidate.
- Developement - Development is the latest and most up to date version of AoTTG 2. Any development changes will be moved into the development branch. This branch is updated by issue branches.
When you are working on an issue, you cannot directly commit your changes onto any of the above mentioned branches. They have protection rules, and that means that you can only get your changes into those branches by making a pull request. What a pull request does, is that you "Request" your changes to added into one of the protected branches. A pull request requires review from at least one reviewer, so this ensures that any changes you make, will always be checked and reviewed by one person.
You can recognize an issue branch by this syntax: #ISSUENUMBER-ISSUEDESCRIPTION (#1-Adding-New-Titan-Hair)
So, when you start working on an issue, you first need to make an Issue Branch. An issue branch is a copy of a protected branch. You can add all your changes in the issue branch, commit it, and then do a pull request. The reviewer may give feedback, which you have to apply, but once approved, your changes are within the protected branch.
It's very important that you create your issue branch from the development branch, or else you may work with an outdated version, and that can ultimately result into you having your work to be redone.
This is intended for Art Team and Mapping Team. Development Team is recommended to use Github Visual Studio, Gitbash or their own preferred Git tool
Within Git, there's four key terms that you have to remember:
- Fetch Origin - With Fetch you can get information about the latest commits to the branches. Your local system does know that the branches exist, but it doesn't automatically refresh that information. Perhaps the information is outdated already. As a good practice, click on "Fetch Origin" every time you want to start working on AoTTG 2.
- Clone - With cloning you download a branch on your own machine.
- Pull - Get incoming commits from a branch
- Push - Push your commits to the server
There's many ways on how you can work with Github. The easiest option is to install Github Desktop. It offers a GUI, and is simple to use.
Once the download is complete, install the program and run it. You are asked to login, so login with your Github credentials. Now that you are logged in, follow the magic screenshots.
Find the AoTTG-2 repository within Github Desktop, and click on Clone
A popup will appear which shows: This url: https://github.com/AoTTG-2/AoTTG-2.git Then change the installation path to your preference, and click on Clone.
Github Desktop will now clone the repository to your system. Depending on your internet speed, this may take a few minutes. Grab a coffee, chocolate milk or tea, and get yourself a cookie. It's important to take sufficient breaks.
A popup may appear which states that this repository uses Git-LFS. LFS stands for Large File Transfer. If this popup appears, please click on initialize Git LFS. This significantly reduces the repository size, as Git will compress Large files.
All done? Perfect! You now have AoTTG 2 setup with Github Desktop!
As mentioned before, we are using issue branches. This allows us to work together without being in each others way.
Your screen should now look like this:
To create an issue branch:
- Click on "Current Branch" and select the branch that your team needs. Ensure that it now says: "Current Branch Development".
- Click on "Current Branch Development" again, and select "New Branch".
- Set the branch name to: #ISSUENUMBER-ISSUEDESCRIPTION (Example: #1-Adding-new-titan-hair, Issue 1, where the Issue is about Adding new titan hair.). Select Create Branch Based On Development!
- Verify that your issue branch has the correct name syntax, and that you create the branch based on Development! Click on create branch.
Your branch is now created locally. Github does not push your changes automatically to the server, as its by design that your changes are only available at local by default. At the top right, click on "Publish branch", and your branch is now available on the Github for everyone. If you cannot publish your branch, please contact your team manager. You can verify this by checking Github Branches.
You can now start working on your issue.
Sometimes you are required to change branches if you are starting to work on a different issue.
- Click on Fetch Origin to get the latest branches
- Click on "Current Branch"
- Select the branch that you want to switch to. Assure that it starts with
origin/
If you are working on LARGE issues, it's recommended that you commit your work to Github once a day. This is to ensure that your changes will not be lost in case something happens!
Now that you started working on your issue, and you are satisfied with the results, or want to push your current work for some feedback, you will have to commit these changes. Luckily for you, Github Desktop makes this very easy.
Open Github Desktop again, and you now see all files that you have changed.
Please review each file and see if you actually intended to change this file. All these changes will become available on your issue branch once you've committed them. If there's a file that you did not intend to change, select that file, right click and select "Discord Changes". This will undo the changes that you made to this file, and revert it back to its previous state.
Once you are satisfied with the result, write a commit description which briefly describes what your changes are, and select "Commit to #ISSUENUMBER-ISSUEDESCRIPTION".
Your changes are now locally committed, you still have to push them to the server. To do that, click on "Push Origin" at the top right, and now your changes are available on the server.
Once the issue that you worked on is done, you must create a pull request. This can be done on the Github site itself. Go to Pull Requests and select "New Pull Request". You will see two branches here now:
- base - This is the target branch. This should always be development
- compare - This is your issue branch.
Correctly configure base and compare, and click on Create Pull Request. A reviewer is automatically assigned, and now sit back, relax and wait for your work to get reviewed. If it gets accepted, then your changes are officially part of AoTTG 2. Wooooh!
If your pull requests states that there's a merge conflict, please contact a member of Development Team for further assistance
During the development of AoTTG2, changes are frequently made. Sometimes you are required to upgrade your branch with origin/development. This branch is the latest version of AoTTG2.
In order to merge origin/development into your branch:
- In Github Desktop, click on "branch"
- Select "Update from Development" (Ctrl + Shift + U)
Your branch is now up to date with development, and thus you are using the latest version of AoTTG2! If your branch hasn't been updated with development for a while (+1 week), then there might be merge conflicts. Either resolve these yourself, or contact the development team for assistance
Thank you for reading this wiki page. Hopefully you should have all the required knowledge for Issues, Branches and Version Control. It might seem like a lot, but believe me, this is the most efficient and communicative way we can work. Now it's your turn to get started on the issues, and good luck!
Remember, if you ever need help, just ask!