Github Desktop Tutorial

If you have not used git or GitHub before, and are not planning on using particularly advanced features of git/GitHub, then GitHub Desktop is a good tool for publishing your additions to our project. It is available for both Windows and Mac; I'm on Windows so that is the version I'll describe, but I believe they are very similar.

Warning: I use git, not GitHub Desktop, for my own changes. I've gone through this myself and believe my tutorial is correct, but it is possible I have overlooked something important. Please ask if you are confused, if you have any questions, or if you believe I'm in error.

##GitHub Account I recommend setting up a GitHub account prior to installing GitHub Desktop. If you do not already have one, you can create your account here. Once you have an account, you should create a fork of the main project by going to https://github.com/MoreEventsMod/More_Events_Mod_Beta while logged in and clicking the "Fork" button at the top right.

Once you've set up your account, you may wish to poke an Admin to be added to the More Events Mod organization, but this is optional.

##Installation First download GitHub Desktop. Run the installation file you downloaded; it will walk you through the installation process, and will automatically start the program at the end of installation.

##Setup The first time the program runs, it will ask you to set up some basic information. Fill this out. You should know that the name and email address you provide will be made available to anyone who looks at your contributions to any GitHub project.

##First Use After you've filled out the setup information, the program will automatically start a tutorial. Going through this tutorial will show you how to do the basic tasks of git: creating a new branch that you will make your changes to, committing your changes to this branch, and submitting a pull request to have your changes added to the project.

The "Tutorial" repository created by doing this tutorial is private, so if you ever want to experiment with how GitHub Desktop works without changing project files, this is a good place to do it.

##Adding the More Events Mod Repository Once you are done with the tutorial, you will want to add our project's repository in GitHub Desktop. Click the + symbol at the top left. This brings up a menu with three tabs on the top. Click the tab labeled "Clone". You should see "More Events Mod Beta" appear in the list (if it doesn't, you may not have forked the project; you can do this online). Click this menu item, then at the bottom click the check mark which says "Clone More Events Mod Beta".

This will bring up a menu which asks you to choose a file location. I strongly recommend installing in .../Paradox Interactive/Stellaris/mod, as this will mean you can test your files without having to copy them anywhere. WARNING: If you already have a More_Events_Mod folder in this location, you will need to move it somewhere else before doing this step. This will copy the files from the GitHub project to this location. If you have made changes to the mod that are not yet reflected in the project (technically: on your fork of the project), then you will have to copy those changes from wherever you moved those files to back into the cloned repository you just made.

##Checking Out a Branch to Edit Near the top left is a drop down menu in which you select which branch you want to work on. If you haven't changed this, it will probably be "master". If you are adding a new feature, this is correct. If you are modifying an existing feature, you should change this to the name of the feature branch you want to edit. (You can learn more about our project's branch structure here.)

##Sync Changes To save changes in GitHub, you have to commit them. To commit them to your current branch, make sure you are on the "changes" tab (not the "history") tab. Then write a short summary of what you changed in "summary", optionally write a longer description of what you changed in "description", and click "Commit to [branchname]".

If you have made some changes that you want to make available to others but which you don't want to submit to the main project yet, click the Sync button in the upper right corner. This will upload your changes to your fork on git, but will not do anything to the main mod. If you want feedback on what you've done, you can direct people to your fork.

##Submitting a Pull Request Once you have made some changes that are ready to be incorporated into the main mod, click the "Pull request" button in the top right. Write a title and description that will let our moderators know what the purpose of your submission is so they know whether to include it.

If you commit any further changes to the branch you've submitted the pull request for (and sync them -- but that might happen automatically), then the pull request will change to reflect your changes. This is good if you need to amend things, but otherwise don't commit changes you don't want to go into the main project when you have an outstanding pull request.

##Your first branch If you want to commit changes while you have outstanding pull requests, or if you want to work on multiple features at the same time, you will want to use branches. To do this, click the branch icon (in the top left of the non-sidebar window), and give it a name. For a beginner, I recommend creating a branch called "development" for changes you are working on, and use the branch "master" for changes you are ready to have included in the project. If you're working on more than one feature at a time, I recommend a branch for each feature.

These are the basics. Let me know if you have any questions, think I made a mistake, etc!

##More Information The official getting started page: https://help.github.com/desktop/guides/getting-started/