Fractal Softworks Forum

Please login or register.

Login with username, password and session length
Advanced search  

News:

Starsector 0.95a is out! (03/26/21); Blog post: Skill Changes, Part 2 (07/15/21)

Author Topic: Guide: Easier Mod Releases Using GitHub Actions  (Read 934 times)

Wispborne

  • Commander
  • ***
  • Posts: 171
  • Discord: Wisp#0302
    • View Profile
Guide: Easier Mod Releases Using GitHub Actions
« on: December 27, 2019, 12:31:59 PM »



TLDR
Setup
0. Download: https://github.com/davidwhitman/stories/raw/master/GitHub-Actions-Starsector.zip
1. Extract zip into your mod directory (which must be hosted on GitHub).
2. Open `~/.github/workflows/runner.sh` and change `MOD_FOLDER_NAME=My-Mod` to your mod folder name.
3. Commit and push these changes, then create and push a new tag.

Usage
- Step 1: Create a release tag
Code: bash
git tag 1.0.0 && git push origin 1.0.0
- Step 2: Wait a few seconds. A release is automatically created with your zipped mod with the version appended so that users won't merge folders when updating

Main Guide

Who is this guide for?
Any modders who wish that they could create a new release of their mod with a single terminal command.
The new release also has a customizable blacklist to strip out things like psd files, .zips, and other stuff you don't want in your distributable.

This does use the version tracking program git. Basic usage of it is not complicated, but it is a very powerful program and if you wander off the simple workflow path, it can be difficult to fix things. It is the industry standard for software developers, used to sync, back up, and track changes to code (and other files), making it very easy to see changes over time and/or restore previous versions.

You should have basic familiarity with the Terminal/Command Prompt, such as how to open it and navigate to your mod folder.
You do not need to know how to use git to follow this guide, but you will learn the basics.

"Hmm, how should I distribute my mod?"

This is a question that every modder has to answer at some point. There are a couple of options.

- Google Drive or other file upload site; Pros: simple. Cons: can't find earlier mod versions easily, no system for tracking code changes, must manually create zip files.
- Bitbucket/GitHub using git + downloads/releases section; Pros: easy to see other available versions, can track code changes. Cons: must manually create zip files, not as simple as GDrive
- Bitbucket/GitHub using git + downloads/releases section + continuous integration; Pros: everything. Cons: not simple, which is why there's this guide.

What does this guide actually cover?

- How to get started with git and GitHub, using guides that other people have already written.
- How and why to add meaningful versions to each release of your mod.
- How to set up GitHub Actions to automatically create a new release of your mod whenever you assign a new version (aka "push a tag to github").


The Guide

If you already have your mod hosted on GitHub, skip to step 5.

1. First, you need a GitHub, account and a repository for your mod.
  - Sign up for an account at https://github.com/
  - In the top-right corner, click "+", then "Add new repository"
  - Name it after your mod and click "Create repository".

2. At this point, you may be wondering what git, GitHub, and repositories are. If so, take a read through this guide for an introduction: https://guides.github.com/introduction/git-handbook/.

3. Now you'll need to install git. There are two options: terminal-based or visual-based (the visual-based ones simply hide the terminal behind nice buttons and stuff).
  - The terminal is the most powerful and ubiquitous, so that it what I recommend and what the guide will describe. However, feel free to use a UI-based git client and perform the same steps using it; I'd recommend GitKraken, which is free to use for Open Source projects. Sourcetree is good as well.
  - Follow the relevant guide to install git on your operating system here: https://www.atlassian.com/git/tutorials/install-git#windows
  - You should now have a terminal open that recognizes the command "git" by printing out a bunch of information on how to use it.

4.  Navigate to your mod folder (typing "ls" should show your "mod_info.json") and let's get your code up on GitHub.
  - Type "git init" and hit enter to create a git repository.
  - Type "git add ." and hit enter.
      - This marks all files as "staged", which means that they will be included when you make a snapshot ("commit").
      - Note: make sure that your mod folder does not include anything other than your mod (eg don't include starsector.api.jar or lazylib.jar). If it does, look up how to use a .gitignore file.
  - Type
Code
git commit -m "Initial commit"
and hit enter.
      - This creates a snapshot of your mod, called a commit. It doesn't upload it; right now it only exists on your computer. You can always type "git log" to see your commits (press "q" to get out).
  - Open your repository on GitHub (it will still be empty because we haven't uploaded anything yet), click "Clone or download" and make sure "HTTPS" is selected ("Use HTTPS"). Copy the text, which should look similar to https://github.com/your-name/your-repo.git.
      - If you don't want to enter your password every time you make a change, you can instead use SSH and create an SSH key, but you will need to figure that out yourself :)
  - In the terminal, type
Code
git remote add origin <paste url here>
and hit enter, then type
Code
git push -u origin master
    You'll need to enter your GitHub password.
      - This tells git where to upload your mod to, then goes ahead and uploads ("pushes") it.

5. If you look at your repository on GitHub, it should now have your mod files! Now we just set up GitHub Actions, which automates releases for you.

0. Download: https://github.com/davidwhitman/stories/raw/master/GitHub-Actions-Starsector.zip
1. Extract zip into your mod directory (which must be hosted on GitHub).
2. Open `~/.github/workflows/runner.sh` and change `MOD_FOLDER_NAME=My-Mod` to your mod folder name.
3. Commit and push these changes, then create and push a new tag.
Code: bash
git tag 1.0.0 && git push origin 1.0.0
« Last Edit: April 13, 2021, 11:44:02 PM by Wispborne »
Logged

Wispborne

  • Commander
  • ***
  • Posts: 171
  • Discord: Wisp#0302
    • View Profile
Re: Guide: Easier Mod Releases Using GitHub Actions
« Reply #1 on: April 13, 2021, 03:39:37 PM »

Updated to be far simpler by removing CircleCI and using Github Actions instead.

Now only two steps to set up: Unzip into your mod, then set your mod folder's name in a text file.
See the new tldr sections up above.
Logged