So far in our intro to FOSP series we have looked at:
- The major components of the architecture
- Walked through installing and setting it up a web server
- Dove into the basics of Bonfire and its modular architecture
If you’ve come this far, thanks for following along. I’m glad to say it’s time to dive into the good stuff and get our hands on some source code! All source code for the FOSP is hosted on Github.com and since the FOSP is modular by design; all the projects that are built for it are stored as separate repositories on the site.
For the purpose of this tutorial, were going to check out and make a change to the main FOSP module, the Online League Manager. We will add a simple entry into the modules English language file, save and commit it to a custom fork of the project and submit it back to the parent project. So let’s get started.
[YOUR NAME]: GIT; GIT: [YOUR NAME]
If you don’t already have one, you’ll need to go to Github.com and set up a new user account. The free account is fine for our basic coding need so select that and fill in your info. Once you’re signed up you will have a personal area to create repositories, hack on FOSP code and share your work with others.
To work with Git based repositories on Github.com, you also need a copy of GIt setup on your local computer. If you’re not familiar with Git yet, I recommend you first visit the Git crash course tutorial to understand the basics of the tool.
Next you’ll want to follow Github’s own tutorial on installing and setting up GIt for use on Windows. They have OSX and Linux tutorials as well.
HEY FOSP, FORK YOU!
In Github, projects can be cooperatively developed using a process that involves first forking, or making a copy of a project for your account, and then sending changes to the original project owner via pull requests, which summarize your changes and allow for discussion between you, the original author and the Github.com community.
If you have the FOSP version of Bonfire installed, open the “bonfire/modules” folder and create a new directory named “league_manager”. (If you don’t have the FOSP setup, you can download the latest version and then continue).
Github provides another great tutorial on forking projects and getting the code on your local development environment. Follow the instructions on that page and create a custom fork of the OOTP Online League Manager Module and pull the latest version of your OOLM fork into the “league_manager” folder above.
HACK, COMMIT AND PUSH A CHANGE
For our example, we’re going to make a simple text addition to the English language file in the “league_manager/languages/english” folder.
Open the file “league_manager/language/english/manager_lang.php”. Scroll to the bottom of the page and add the following line:
$lang[‘test_string’] = ‘This is a test string’;
Save the file and close it.
For our example, we’ll use the helpful Git GUI to commit and push our change.
- Right click on the league_manager folder and select Git GUI here….
- In the Unstaged Changes pane, the manager_lang.php file should be listed.
- Click the Stage Changes button to stage (which performs a Git -> Add operation) the file.
- In the text box at the bottom of the screen, add a commit message like “Added testing text line”.
- Click Commit. This commits the change to your local Git repository. The Staged Changes box should be empty now.
- Click the Push button to initiate a push to your Github repository.
- In the Push dialog click OK. You’ll be promoted for you’re SSH passkey.
- Enter it and click OK.
- You should see a status dialog which hopefully turns green. If so, your change has been pushed to your Github.com repository.
- Browse to your Github.com repository to see the update.
SUBMIT A PULL REQUEST
Now let’s say we made an important change to the OLM module and we want to send it back to the parent project. This is a simple process.
Browse to your forked version of the OOLM project. In the top right, click the Pull Request button. The first view of the page, Preview Discussion tab, will display a text box for you to enter a message to the parent project author. It should describe the changes you’ve made and why they were made.
NOTE: If you are working in a different branch that the parent project, for example develop instead of master, or you wish to submit your change to a branch other than the parent’s default integration branch (which is usually master but can be custom configured by the repository owner), you can change them as seen here.
The Commits tab shows all commits made to the repository that differ from the parent repository. The Files Changed tab shows a line by line view of every change. This screen is exactly the same for the developer receiving the pull request so they can review the differences and decide whether to accept the pull request or post a discussion on the request.
Once you are satisfied your request is ready to be send, click Send Pull Request.
IMPORTANT NOTE:
When submitting pull requests, it’s important to note that any subsequent commits that you make to the branch you attached to the request will be automatically included in the pull request. It is therefore recommended that you create a new branch that will contain only the specific changes you wish to send back to the parent repository and create a pull request off that specific branch. Otherwise, you risk having your pull request rejected if additional changes are added before the request is pulled and closed.
FURTHER READING
More on Git:
- I recently came across this in depth tutorial on Git which I highly recommend: Understanding Git Conceptually.
- I also thoroughly recommend listening to Linux and Git creator Linus Torvals discuss Git at Google
More on Github:
- A more detailed walkthrough of this process can be found on the Github help sending pull requests and the Work with branches section of the Fork a Repo page.
So that’s it for this lesson. Today we’ve:
- Set-up Git and a Github account
- Forked and pulled the code for the OLM module
- Made a change
- Committed it to our custom fork
- Sent a pull request up to the parent project
In the next tutorial, we will dive head first into the development of a full standalone FOSP module, the Team Stats List. See you then!
Download the FOSP Today!
Download the latest stable release version from the official FOSP web page. All the documentation you need is available in the installation and setup guide.
Contribute to the development and help the FOSP grow
The FOSP is a 100% free and open source project. The source code is publicly available on GitHub.com. If you want to contribute to the development, simply head over to my official Github page, fork the related projects, hack the code and send pull request with your updates. It’s that simple.
If you’ve built an FOSP module let me know and I’ll add it to the "Built on the FOSP" list.
Want to help test?
Testing assures everything works as expected and that everyone gets the best fantasy experience possible. Simply download and test the site and log issues on the official Github issues pages. Each portion of the site has its own page and issues list so be sure to log the issue in the appropriate module portion of the site.
Donate
While the FOSP is free to download and use, we do very much appreciate any donations made towards its development.
