-
Notifications
You must be signed in to change notification settings - Fork 36
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.
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 may want to 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. This allows you to upload personal changes for anyone to see without affecting the main repository.
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.
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.
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.
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.
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 MoreEventsMod/More_Events_Mod_Beta appear in the list (if it doesn't, you may not be added as a collaborator on our repo; ask an admin for help). 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, then you will have to copy those changes from wherever you moved those files to back into the cloned repository you just made.
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. You likely want to be working on dev instead, although if you are working on an incomplete feature it likely has its own branch, and if you are going to create a new branch you probably want to do so starting from master. (You can learn more about our project's branch structure here.)
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, click the Sync button in the upper right corner. This will upload your changes to the main repo on git. If you want feedback on what you've done, ask people to look at the changes in Discord chat, or open an issue in the tracker.
Note that you cannot make changes to the master, stable, or beta branches (unless you're an admin).
If you are working on a forked repo rather than the main repo, and 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.
If you want to work on multiple features at the same time, or if you want to submit upload work for an incomplete or untested feature for any reason, 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. I strongly encourage you to name the branch after the feature you are implementing in it.
These are the basics. Let me know if you have any questions, think I made a mistake, etc!
The official getting started page: https://help.github.com/desktop/guides/getting-started/