User:Gumi/Dev:Guide
How to develop for dummies
This tutorial assumes you are using Linux. If you are using windows, you need to set up a virtual machine.
Initial Setup
This tutorial assumes you are using the Bash shell. If you are using any other shell bugs may happen.
Installing the dependencies
Debian derivates (including Ubuntu)
- Open a terminal.
sudo apt-get install g++ python2.7 make realpath git
Fedora derivates
- Open a terminal.
sudo yum install gcc-c++ make git
Creating a github account
- Go to https://github.com/join and fill the form. When asked for a plan, choose the free option.
- Confirm your e-mail address and login to your account
- Go to https://github.com/settings/emails and check "Keep my email address private"
- Go to https://github.com/settings/profile and under "Public email" choose the address that ends with @users.noreply.github.com
- Save your profile
Setting up the global git environment
- Go to https://github.com/settings/tokens and click the button "Generate new token"
- Choose any name you want for the token.
- Check those permissions: repo public_repo user:email write:repo_hook repo:status read:public_key user repo_deployment
- Copy the personal token. It will look something like this: 46cc23de2f02e4t08536803ve705d8241e62e527
- open a terminal
git config --global credential.helper "cache --timeout=3600" git config --global user.name "Your Name" git config --global user.email "<username>@users.noreply.github.com" touch ~/.netrc chmod 600 ~/.netrc
- open the file ~/.netrc in your favorite text editor and put this inside
machine github.com login <username> password <token>
- save the file and close the text editor
Forking and cloning
- Go to https://github.com/themanaworld/tmwa and click the "Fork" button
- rinse and repeat for
- open a terminal
echo "export PATH=$PATH:~/bin" >> ~/.bashrc source ~/.bashrc mkdir ~/tmwAthena cd ~/tmwAthena git clone --recursive https://github.com/<username>/tmwa.git git clone --recursive https://github.com/<username>/tmwa-server-data.git
Setting up the remotes
- open a terminal
cd ~/tmwAthena/tmwa git remote add upstream https://github.com/themanaworld/tmwa.git git fetch --tags --all cd ../tmwa-server-data git remote add upstream https://github.com/themanaworld/tmwa-server-data.git git fetch --tags --all cd tools git remote add upstream https://github.com/themanaworld/tmw-tools.git git fetch --tags --all cd ../client-data git remote add upstream https://github.com/themanaworld/tmwa-client-data.git git remote set-url origin https://github.com/<username>/tmwa-client-data.git git branch --set-upstream-to=origin master git fetch --tags --all
Copying the local config files
- open a terminal
make conf
Making an admin account
- open a terminal (and leave it open)
cd ~/tmwAthena/tmwa-server-data
./run-all
- wait until it says "Map-server 0 loading complete.". If after 2 minutes you do not see this message, ask for support on IRC.
- while keeping the other terminal open, open a new one
cd ~/tmwAthena/tmwa-server-data/login
tmwa-admin
add <username> M <password>
gm <username> 99
exit
- close this terminal but keep the one in which you typed run-all
Making a custom manaplus launcher
- open your favorite text editor and paste this inside:
#!/bin/bash manaplus --server localhost --port 6901 -u -d ~/tmwAthena/tmwa-server-data/client-data
- save the file in ~/bin and name it "m+"
- open a terminal
chmod +x ~/bin/m+
Testing the server
- While your terminal in which you typed run-all is still open, open a new terminal
m+
- You will see the login screen. Type the username and password that you have set at the step "Making an admin account"
- You should now be able to create a character and use the server. If it does not work, seek help on IRC.
Making new content
Branching
A branch is a version of the code each branch is a different version. By default, when using git, you are on the master branch which is the main version. However, when using forks, your master branch should always stay a perfect copy, a mirror of the master branch of the original repository (upstream). When you want to make a modification you should always create a new branch. Never work on the master branch.
Let's say you want to make a modification to client data:
- go to https://github.com/<username>/tmwa-client-data
- If it says "This branch is even with themanaworld:master" you can proceed. If it says the branch is behind themanaworld:master, follow the steps of "Updating from upstream". If it says the branch is ahead of themanaworld:master please seek help on IRC.
- Click on this button (on github, not on this wiki page) :
- Type the name of your new branch. The name can be anything. If, for example, I wanted to work on the npc "Eurni" I could put something like "eurni-update" as branch name.
- open a terminal
cd ~/tmwAthena/tmwa-server-data/client-data git fetch origin git checkout <branch>
Adding changes
- Make sure you are not working on the master branch. You can check your current branch with this command:
git rev-parse --abbrev-ref HEAD
- Modify the files you want to change.
- Test it by running the server (with ./run-all in tmwa-server-data) and launching m+
- Mark your changes:
git add path/to/file
- Review your modifications:
git status
- Commit and add a summary of your modifications
git commit -m "put a short summary here"
- When you are ready, push your modifications to github:
git push origin <branch>
Making a pull request
- After you have pushed to your branch (NOT master), go to the address of your repository. For example: https://github.com/<username>/tmwa-client-data
- You should see a new button: click it (on github, not on this wiki page). If you do not see this button, you probably did something wrong so seek help on IRC.
- Put a title, a summary and click on "Create pull request"
After you make your pull request, you need to wait. A developer will either tell you what is wrong with your code and how to fix it or, if everything looks fine, add the "test" label. The test label means your modifications can be tested on the test server.
Updating from upstream
to-do: explain how to pull from the tmw repo and force-push to the fork