Contributing With Github Desktop like i'm 5

Introduction

This guide aims to explain the two core parts of contributing to the bar game as simply, and in a step by step method, as possible.
It is split into two parts, the inital setup that you should only ever need to do once, and the repeatable contribution loop.
_{*and Useful Tools.}

Setup w/ GITHUB DESKTOP

You will need a github account, make sure you are signed in, and if you don't have one create one now.

1. Creating a Fork

You will now create your own online copy of the game, to do so, press the following link,
And tick "Copy the master branch only".
Create Fork: https://github.com/beyond-all-reason/Beyond-All-Reason/fork

This copy you are allowed to edit, and it is from it that you will make requests to add back to the core game repository (copy of game files).
It is reffered to as a FORK, it is a copy that is aware of the orginal files that it is copied from, and as such:

It can be easily updated to recive the same changes as its parent.
It can easily make Pull Requests, PRs for short, to update its parent copy with your changes and additions.

More on how to do this and how to use this fork later.

2. Download Github Desktop

Next you will need to download and install Github Desktop, you can do so here:
https://desktop.github.com/download/

This is a client UI that will make using Git a lot easier, as git itself offers a lot, and is command line based.
Git is used to save your changes in versioned increments so that you can return to them later if things don't work out.
As well as to backup your work online, and more easily colabarate on the same mutli file project with other.

3. Preparring your local files

Now you will make a local copy of your online fork, so that your game can read it, and so that Github Desktop can see the changes you make.

Open Your File Browser, and navigate to your game's folder.
_{(you can do so via the game launcher if you don't know where you saved it)}
Then go to the data folder _{(the launcher's landing point)}, and then create two things:

A textfile named devmode, or devmode.txt if you can see file extensions
A folder named games

In the games folder create another folder named BAR.sdd, note the sdd, not to be missread as ssd.

Downloading Your Fork:

[EXPAND] New Github Desktop Users

If you are a new user you will have a List of Your Repostatories on the Left Half of the UI.

Select your fork of the repository: "your_name/Beyond-All-Reason", and press Clone your_name/Beyond-All-Reason.
Set the Path to your BAR.sdd folder.

[WARNING]
Make sure to remove any trailing '\Beyond-All-Reason'.
The Path should end on '\BAR.sdd'

Your download should look something like this, Good Job! (this may take a few mintes)

Afterwards Select: "To Contribute to the parent project".

[EXPAND] Returning Github Desktop User

In Github Desktop Press the Current repository Button, then Add, and clone.
In the Clone menu: select your Fork of the Beyond All Reason Repository, and set your path to your BAR.sdd folder.

[WARNING]
Make sure to remove any trailing '\Beyond-All-Reason'.
The Path should end on '\BAR.sdd'

Afterwards Select: "To Contribute to the parent project".

[EXPAND] Verifying File Path / Common Issues

If you accidentally didn't remove the trailing Beyond-All-Reason folder, rename it to BAR.sdd,
then drag it out into the games folder, as to not accidentally miss any hidden files such as the ".git" folder.
Lastly, when Github Desktop complaints point it to the only BAR.sdd folder.

To verify Your File Path, you should be able to find the following structure:
C:\ [..] \Beyond-All-Reason\data\games\BAR.sdd\.github

If, despite verifying the above path, you aren't seeing the developer tab in the main menu settings, and/or your singleplayer shows Update as Missing, then verify that the folder you think your BAR is in, is the one that BAR has been updating to and using. To do so open the folder via the launcher.

If you aren't seeing your changes in the game:

If You are working on WIDGETS:
Make sure you don't have a custom version of the widget in your game/data/luaui/widgets folder.
If You are working on UNITS:
- Working On an Existing Unit:
  Did you create a Backup Copy of the Original Unit File? That Copy may be overwriting your changes if you haven't changed the internal unit name inside.
- Working On a NEW UNIT:
  If you aren't able to spawn your unit in, Check game/data/infolog.txt for your unit's internal name, it should be there with an error.
  If your Game is Crashing, Your Unit Def File is missing an important Parameter, Check game/data/infolog.txt, tho it is noted down as a WARNING rather than ERROR and it may not specify why it didn't like the unit.

4. In Game Dev Mode

Launch the game as normal, leave the launcher config as normal, set to Alpha.

You will now see a new tab in the Settings panel of the main menu, Open this Developer Settings Tab.
Then near the bottom you will find a Singleplayer optinon, set it to Beyond All Reason Dev.

Now if you go into skirmish singleplayer, (it may take a minute or two after pressing the button) it will show the version as BAR $VERSION instead of the normal: BAR-(number of commits)-(commit hash).

If the update is shown as missing instead of Ready: Veryfing File Path Section

Launch the game, press enter, and type /widgetselector to open and add the widget selector to your F11 key.
Next in this widget selector Search for Auto Cheat and enable it.

You shouldn't need to Revist Any of the Prior Steps, instead updating your Fork as needed.
Your Local Dev Enviorment for the Game Side should now be fully setup.

Thank You For Contributing. ❤️
- The BAR Dev Team

See Next: Useful Tools, Links, & Commands
See Next: Basic Contribution Loop

Useful Tools and links

Useful Commands And Widgets

Widgetselector & Autocheat

If you haven't previously enabled the widget selector and auto cheat, you can do so as such:
In a game match, press enter and write: /widgetselector to open and add the widget selector to your F11 key.
Next Search for Auto Cheat and enable it. This will automatically run the /autocheat command in your singleplayer dev

Useful commands:

Press Enter, and write any of the following. it mostly doesn't matter if the normal ui crashed or not.
CHEATS:
/cheat : enables cheats.
/nocost : disables build costs, both time and resource, breaks some minor things.
/give resourcecheat : gives a resource generator and storage so that units still take time to build.
/give internal_unit_name : spawns in a unit at mouse cursor
/give [amount] unit [team] : above + amount, teams start at 0, zero being most likely you, in a 1v1 team 2 is gaia
You can find internal unit names here: [English Unit Names File] or here for non-english [Languages] / units.json
DEVELOPMENT
/luarules reload : Force Restart and reload game rules in case they broke.
/luaui reload : Restart the ui. For Individual Widgets: they auto restart/reload when changed, if crashed restart via widgetselector.
/reloadcob unit : Reload the COB (compiled BOS) of a unit, for lus reload luarules
See Here for more : https://springrts.com/wiki/UI_commands

[Visual Studio Code]

The game side code, not engine, is writen primarly in LUA and OpenGL.
VSCode can support markdown (colored highlighting) for both of these via extensions.
These extensions can be downloaded and installed using the build in market for free, we recommend:

Lua, BY sumneko, Lua Language Server coded by Lua

To best use this Editor:
- right click on your BAR.sdd folder, and press the new option: Open with Code.
-or-In Github Desktop go to Repository in the top menu bar, and Open in Visual Studio Code.

More Resources:

Additional Resources / Information can be found here:

https://github.com/beyond-all-reason/Beyond-All-Reason/wiki/Resources-and-links
Our Discord Server:
https://discord.gg/beyond-all-reason

Contribution Loop

Basic loop

[EXPAND] Basic Flow Graphs

flowchart TD

subgraph IDEA["Entry Point"]
direction LR
  NEWIDEA["New Idea"] --> UIDAE["Make Suggestion
In Discord Thread"]
  UIDAE --> NO["Denied"]
  NO --> SAD["It Happens"]
  ISSUE["Spot Issue"] --> FIX["I Want To Fix It"]
  ISSUE --> NOFIX["I don't know how to fix it"]
  NOFIX --> TICKET["Make / Revive
Github Issues Ticket"]
  UIDAE --> YES["Approved"]
  YES --> MAKE["New Brach"]
  FIX --> YES
  
end

subgraph WORKFLOW["New Branch Workflow"]
direction LR
    A["New Branch"]
    B["Do Work"]
    C["Commit"]
    D["Push"]
    F["Open A Pull Request
(If you haven't made one)"]
    G["Get Feedback"]
    H["🎉Merged🎉"]
    A-->B
    B-->C
    C-->D
    C-->B
    D-->B
    D-->F
    F-->G
    G-->B
    F-->H
end

IDEA --> WORKFLOW

Start

Branch:
Branches are basically seprate workspaces for the project.

WHEN TO MAKE A BRANCH
You will want to make a Branch for every Change, Addition, or a Fix, that you want to Implement.
Thus keeping your work spertate and progress and issues isolated to each branch.

HOWTO:
To make a new Branch, press the current branch button in the top bar, and press New Branch.

Work Loop

Commit:
Commits are a like an undo-able save. They are states that you can go back to, and mark progress of your work.
Each commit is a set of changes to the previous state of the file.

WHEN TO COMMIT:
You should Commit your changes at every milestone you make where the code works, or checkpoint state that you may wish to go back to.

COMMIT MESSAGE:
A Commit message should be a short description of what was done to the files, or what it achives. E.G. "Removed redundent checks" or "Fix accelerate to infinity bug".

HOWTO:
Commit Message and Commit Button is at the bottom of the Left Hand Changes Panel in Github Desktop.
Make sure your wanted Changes are selected in the left panel.

Push:
Pushing puts your Local Staged Changes (aka the ones commited) up on your Remote Repository (online).
Thus backing them up, letting you access them from other devices, and if your Repository is public let others see and pull said changes.

WHEN TO PUSH:
How often you push is up to you, But you should aim to Push when a feature is complete.
Or when you feel unsafe not having your work and progress backed up online.

[OPTIONAL] If your Commmit History is Messy
If you switch the Left Panel from Changes to History, you will see the current Branch's Commit History, as well as your Staged, aka Un-Pushed, Commits marked with an Up-Arrow. If your List of Staged Commits looks messy you may Squash them.
You can also Squash Pushed Commits, and then Force Push, but this is unfavorable as it changes the Writen History, heavily Inconvening other people that may have viewed, commented on, or pulled your changes.
HOWTO SQUASH:
To Squash, Select Two or More Commits in the History Tab, Then Right Click, and `Squash Commits...`

Where To Find Push Button:

HOWTO:
The Push button is contextual, it will apear to the right of the Current Branch Button, when you have unpushed Commits.

Ending

Pull Request:
A Pull Request is you requesting to add the changes you have made on your Branch to Another Branch, in our case you will most likely want to Request to pull From your Work Branch to `Beyond-All-Reason/Master` Branch to contribute back to the game.

WHEN TO PR:
You will want to make a Pull Reqest when your feature is complete.
Alternatively, you will make a Pull Request or a Draft Pull Request when you need external input on the changes, as to make it easier on others to see and test.

Draft Pull Requests are made like a normal PR, the Create Pull Request after the form has a Drop Down on the right side.

HOWTO:
To make a Pull Request (PR) you can either go to the website of either your fork, or its parent repo. Github will suggest that you make a PR in a large yellow box.
Alternatively or in Github Desktop, in the top Menu Bar select Branch (alt + B), not the Current Branch Menu, and the last option says: Create Pull Request, this opens up the website.

Merge Conflicts:
The Github Website may mention a Merge Conflict, if it is simple enough The Core Team Member or Admin may resolve it themselves before merging.
Alternatively, to deal with a merge conflict, go to github desktop, press Fetch Orgin (It might be in the drop down menu to the right of the Current Branch button), then in the Top Menu Bar go to Branch (not current branch), and `Update from upstream/master`.

Review:
- A fellow Contributor, Core Team member, or Admin will hopefully review your PR, if it is all good they will either approve it, or if within their power and area, they'll Merge it. If approved, but not merged it will get merged by another Core Team member or Admin.
- We aim to review Pull Requets on Thursdays.
Alternativly:
- Alternatively, your PR may have Changes Requested (or unlikely rejected and closed). This feedback will be visible on the PR page and/or within the Files Tab of the PR page within the context of the code. If this happens You should go back to itterate on the feedback, commit, and push.
- You shouldn't need to reopen the PR, only mark requested changes as resolved as you address them, and request a re-review once fully addressed.

Cleanup:
Once the Pull Request has been merged it is pretty safe to delete both the local and online version of the relevant branch.

Reviewing Other PRs & Collaboration

Git isn't limited to solely pulling and viewing your own Repositories.
You can also pull other's pending Pull Requests and Branches to view, review, and/or contribute to them.
The next subheader covers viewing pending PRs, while the one after covers viewing non-pr branches of other BAR forks.

Opening & Reviewing a Pull Request

PRs can be found here https://github.com/beyond-all-reason/Beyond-All-Reason/pulls

To TEST a Pending Pull Request on your machine, you can set your local Github Desktop to the pending PR.

HOWTO:
Select the Current Branch menu at the top, swith the tab to "Pull requests", and select the relevant PR.
Afterwards, on the website you can either comment on the pr, or provide a proper Blocking, Comment, or Approving Review.

HOWTO:
To make such an offical review, you need to switch to the Files Changed of the PR, where you'll be able to mark specific code to request a change, or mark the PR as approved and tested by you.
Then in the Top Right you may confirm your pr, with an optional message, and marking it as one of the 3 options: Blocking, Comment, or Approving.

Opening Someone's NON-PR Branch

You can pull Branches from someone else's Fork, unfortunately to do so you have to perform some Command Line Activity.

Get the link to their Repository.
This will typically be: https://github.com/ + <Their Github Name> + /Beyond-All-Reason
Open The Command Line
Press the Top Menu Bar of Github Desktop, Repository, Open in Command Prompt.
Select a synonym or name.
For how you will want to refer to their reposatory, this can be a nickname, their name, whatever.
Simply replace the parts of the commands with it
Enter the following Commands
This will track, sync, and add their branches to your Github Desktop's Current Branch menu

git remote add <nickname> <reposityory_link>

git fetch <nickname>

You will now see their branches as options to swap to.

To untrack them later:

git remote remove <nickname>

EXAMPLE git remote add:

git remote add robert https://github.com/robertthepie/Beyond-All-Reason
git fetch robert
git remote remove robert

Provide feedback

Saved searches

Use saved searches to filter your results more quickly