The BLOG project is hosted on Github. Contributions in the form of GitHub pull requests.
In the following part of this guide, for anything concerns the sbt file, we will only write it as
sbt/sbt. For Windows users, please use
- Break your work into small, single-purpose patches if possible. It’s much harder to merge in a large change with a lot of disjoint features. Make your branch small enough that only contains one single feature change, multiple features should be completed in seperate branch and pull request.
- Create an issue if you discover some bug or propose a new feature. Put as much label as possible.
- Do not push commit directly to master. Instead, submit the patch as a GitHub pull request. For a tutorial, see the GitHub guides on forking a repo and sending a pull request.
- When creating a pull request, please link to an issue if it already exists.
- Follow the Code Style Guide.
- Large files (e.g. data files > 10MB, any output file, generated pdf etc) should not be added to git repo.
- Update the documentation (in the docs folder) if you add a new feature or commandline option.
- test your code before submit pull request.
Use google java style * 2 spaces for indent * no long lines * Please use \n for line terminator!
BLOG uses sbt for building and releasing packages. The minimal requirement is sbt version 0.13.
To set up Eclipse for BLOG development:
- Download the Scala IDE. This is just Eclipse bundled together with the Scala plugins.
- Generate the Eclipse project file using
- Import the project into Eclipse
Eclipse config file is provided. Please use the version already in git master branch.
To run a BLOG model from within Eclipse:
Run Configurations, create a new configuration
- In the
Argumentstab, pass in the path to the BLOG model, and any parameters
Some things to try if you run into trouble:
- In the Eclipse menu, click Project > Clean
- Right click on the project, click Scala > Add Scala Library to Build Path
Generating Lexer and Parser
You only need to do this if you modified
sbt/sbt lexer sbt/sbt parser
sbt/sbt compile sbt/sbt stage
The second command is to ensure you can run
iblog in development environment.
To make a release
sbt/sbt compile sbt/sbt html sbt/sbt universal:package-bin
Generate Debian installation package
Generate Windows Installation package
You must have WIX installed. Obtain it from http://wixtoolset.org/.
You may also be interested in some Git basics:
The basic unit of code review is a pull request. Here is how you make one. Note you can PR off branches, so there is no need to fork the repo. This is what's referred to as "Shared Repository Model" in the doc below.
How to use Pull Requests
You should create a feature branch whenever you start to work on something. This is the branch you will work off for the entire development cycle. When you finish development on the feature, you will merge this branch back into master. This way, we can ensure that our master branch is always in a good state, and never has anything that is only partially complete.
$ git checkout -b feature_name
As early as you can (you can even do this before you start any work) start a pull request on Github. You should use the PR for discussion about this particular feature as well. Periodically push your code to this branch, which will update the PR. It's recommended that you get your code reviewed at regular intervals rather than all at once.
Managing Feature Branches & Pull Requests
The git motto is that you should commit often. Some people go as far as committing every 5-10 minutes. This is perfectly fine, and recommended for your local history while you work. It allows you to revert easily fi you make a mistake.
However, all these granular commits may not be the easiest thing for a reviewer to address (b/c each commit shows up as a separate page you have to click on and comment). Therefore, you should commit often but squash your commits before you push to the PR.
Updating Your Branch
For long features, your feature branch may fall behind of master a lot. This is bad, since it will introduce difficult merge issues later on (the more you fall behind of master, the harder it is for you to merge your changes back into it). Therefore, you will want to regularly update your feature branch with commits that happened on the master branch.
The desired operation here is a rebase rather than a merge. A rebase will take the history seen on master, and replay it as if they happened on your branch. This has the effect of keeping the history clean, as the only "merge" entries we will see are when we merge feature branches back into master.
The commands you should run to rebase are
git fetch --all git rebase origin/master
When you do push your code after a rebase, you will have to do so with
git push --force
--force option is required since a rebase re-writes revision history, so your local history and the upstream history will disagree.
--force tells git you want to override the upstream history with the rebased history.
Closing a Pull Request
When you get an
LTGM, just click the merge button on github to merge your changes into master.