Feature Development Quick Guide

Intro

This guide will give a brief overview of how to get started developing LinuxGSM by running through some of the basics of using GitHub and the tools you need. This is not a comprehensive guide to GitHub but should help with getting started. There are plenty of resources available online such as the GitHub help documentation that will help you learn more.

Requirements

Before you get started a few tools are required for development. The tools used are down to the developer's preferences. However, there are some recommendations if you are new.

GitHub Account

LinuxGSM uses GitHub to host the code, because of this a GitHub account is required.

Text editor

LinuxGSM is written in BASH and can be developed simply by using a text editor. The recommended text editor is Atom as it is Open Source and is developed by GitHub so has some great integrations. However, if a developer is more comfortable with another editor that is fine. For specific requirements for text editors see Text Editor Settings.

Git Client

To edit code, create branches and submit Pull Requests a Git client is required to work on the project. The recommended Git client is Git Kracken as it is feature-rich and easy to understand the branch relationships. Atom also has a built-in Git Client which is useful for beginners. Both Git Kracken and Atom integrate well with GitHub..

SSH Client

To connect to Linux servers an SSH client is needed. There are various clients available to choose from. For Windows, MobaXterm is a great option or the classic PuTTY. For Linux and Mac Remmina works well for saving SSH sessions.

Test Environment

LinuxGSM runs on Linux and as such requires a Linux environment for development and testing. Most developers will be running Windows but there are multiple ways to create a Linux development environment.

Distro

LinuxGSM is primarily developed on Ubuntu but also tested to work on CentOS and Debian. Different versions of a distro will also have different versions of BASH etc. So be mindful of newer features that might not be available on older supported distros. In general, LinuxGSM will support distros that are still officially supported by the vendor but is also reliant on if the Game Server also supports the distro. See distro for more info.

Virtual Machine

Creating a virtual machine on a desktop or laptop is a good way to create a development environment. Using Virtual Box and downloading Ubuntu Server iso a test environment can be created quickly. However, to test internet functionality there may be a requirement to open ports on a home router.

If spare computer hardware is available, setting up an ESXi or Xen Server may be a good option for a development environment.

Internet Server

VPS and dedicated servers can be rented relatively cheaply and is a good way to test LinuxGSM in the environment it is mostly used (online). There are several providers like Linode that provide servers from $5 p/m and allow the quick deployment of servers with different distros. Some game servers do have higher system requires than others so a more powerful VPS may be required.

There are many providers to choose from but below LinuxGSM developers have used previously.

Chosing an Issue to Develop

Whenever someone raises a new feature request or bug is done on the GitHub Issues page. There is a raft of issues with different levels of complexity. Choosing an issue to work on is down to you as an individual, however, it is important you enjoy working on it. It is recommended that a simple issue is picked first and more complex issues are attempted as you get used to LinuxGSM. Popular issues to attempt are type:Server Requests as often developers want to have a game server added to the project. Be warned however some game servers can be more difficult than others to develop.

To help filter issues GitHub uses labels to help identify the types of issues. Common labels include type:bug, type:feature, command:monitor, game: 7 Days to Die. Labels are split into label types such as type, command, game, info etc to assist in triage.

Starting Development

To begin working on LinuxGSM you need to fork the LinuxGSM repository once forked you will need to clone your new repository to your local machine using your chosen git client. Once cloned it is possible to edit the code on your local machine using your text editor of choice.

It is recommended you create a branch to develop your code. The branch should use the Gitflow methodology and should be named feature/[featurename].

Once a change has been made and saved the change will need to be committed to your local repo. When using commit it is important to leave a useful message to describe the change, this is covered in Conventional Commits. When you are ready to send your commits to your remote fork you will need to push the updates.

Using the Test Enviroment

At some point, you will need to test the code you have worked on. This can be done by downloading LinuxGSM and updating the repo and branch details to match your fork.Login to your development environment and begin installing LinuxGSM

Setup Testing Enviroment

Login to your develop enviroment and begin installing LinuxGSM.

1. Create a user and login.

adduser linuxgsm
passwd linuxgsm
su - linuxgsm

replace [gameserver] with the game server you are developing.

mkdir [gameserver]

2. Download linuxgsm.sh.

wget -O linuxgsm.sh https://linuxgsm.sh && chmod +x linuxgsm.sh

3. Rename the github username, repo and branch to match you one you are developing on.

## GitHub Branch Select
# Allows for the use of different function files
# from a different repo and/or branch.
githubuser="GameServerManagers"
githubrepo="LinuxGSM"
githubbranch="master"

4. Install the game server

./linuxgsm install

Updating the Test Enviroment

Everytime you push to remote it is possible to pull the changes to the test enviroment. This is done by using the development command clear-functions.

To use clear-functions activate development mode.

./gameserver development

Run the command.

./gameserver clear-functions

Create a Pull Request

Once the code you have worded on is ready to be submitted to the LinuxGSM project a pull request will need to be raised. Pull requests have a list of things that need to be completed to get it merged in to the project. Follow these steps as much as possible to ensure that your code can be merged quicker. When the pull request is raised various unit tests will be done on the code to ensure it follows the correct standards. When naming a pull request ensure that it following Conventional Commits standards. As this is what is used for generating the changelog for the next release.

A best practice for writing a commit message is to say in your head the following, followed by the change you are making.

If I commit this change it will.......add slack support to alerts

feat(alerts): add slack support to alerts
fix(csgoserver): remove SteamCMD auth requirement 32-bit workaround

Once the Pull Request is created it is now time to wait. The Pull Request will need be reviewed by LinuxGSM developers who regularly work on the project. They will accept, reject or reccomend changes to the Pull Request. This can take time or your pull request will be held until a time that is appropriate to merge in to the project so please be patient. One of the developers may leave a comment to make changes or make changes themselves to make the commit ready. Once this review proccess is completed congratulations your commit will be merged ready for the next release.