Getting the source
git clone https://github.com/mytestbed/omf.git
Modifying the source
Feel free to modify the code, fix a bug, add a feature, correct a typo in documentation, no contribution is too small. We do have some guidelines, and we do appreciate if you could follow them.
The following ruby coding style will be used: https://github.com/bbatsov/ruby-style-guide
NO TRAILING WHITE SPACES
Please make sure your files do not contain trailing white spaces. Most editors and IDEs can be configured to do it automatically.
If you got existing code that could contain trailing white spaces, simply run this command in root directory of the project:
find . -not \( -name .git -prune \) -type f -print0 | xargs -0 sed -i "s/[[:space:]]*$//"
and then commit the change.
Choose git tag name according to semantic versioning rules: http://semver.org/
Yard is used for auto generating OMF code documentation. Refer to this guide for details: http://yardoc.org/guides/index.html
Meaningful commit message
Please provide a meaningful commit message for each commit.
The commit message should be formatted properly:
Capitalized, short (50 chars or less) summary More detailed explanatory text, if necessary. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together.
You could modify commit message if you realised you made a mistake after committed.
git commit --amend
Test your changes
We are using MiniTest as our unit testing framework, and the integration with Travis CI & Jenkins allows these tests & gem package builds to be executed upon every single commit made.
You can examine test folder under components to find out how test files are organised.
You can execute these tests manually by issuing rake command inside components directory. For example:
cd omf_common; rake
For more information regarding MiniTest, please go to the official site:
Eventmachine in minitest
To test asynchronous eventmachine based code, refer to this minitest pluging:
Sign your commit
You could sign your commit & tag using -s option in git.
git commit -s git tag -s
Share your change
Your changes & hacks made locally could be useful for other OMF users and OMF project in general. Please share your changes with us.
This git tutorial will give you plenty of tips to get started if you need some help regarding git.
Set up git identity
If you want to contribute your changes to us, please configure your Git environment, with at least your name and a valid email address, so we can properly acknowledge your work when integrating your commits. You can do it with:
git config --global user.name "your name" git config --global user.email "your email address"
See git config -h for all options.
The @[email protected] sets these parameters for all your Git repos. You can limit this to the current repo by removing this option.
These options could also be set up via editing .gitconfig file.
Announce your changes
When you are satisfied with your changes, you can provide them to us so we can review them and integrate them into the main tree.
Please create an issue in our issue tracking system http://mytestbed.net/projects/omf/issues so it can tracked.
Then you have these options to provide us the access to your changes
- Prepare a git patch and send it to [email protected].
- Prepare a git patch and attach to the issue you created.
- Send a pull request to [email protected].
- Send a email to [email protected], or simply in the issue you created, provide how we can access your own repository and pull the commits you made. (if you fork OMF via github, your forked repository should be public accessible)
The first two options need you to create patches from the Git branch containing your changes.
The best way to do this is with git format-patch to have export them in a suitable format:
git format-patch origin/master..HEAD # Assuming you started working from origin/master
If your repository is publicly accessible (e.g., on a server with anonymous read access or GitHub), you can also send us a pull request, using git request-pull.
git request-pull origin/master http://url/of/repo # Assuming you started working from origin/master
Manage your own repository
The flexibility of new OMF design means that you could develop your own resource proxy to meet certain specific needs, which might not be needed as part of core OMF system. For example omf_rc_openflow, a plugin which extends OMF to provide a set of Openflow related functionality, has been set up as a separate git repository, managed by its maintainer, and released regularly via rubygems.
Please consider the following:
- Start such repository only if you think it won't be necessary for OMF core system to include such features.
- Once your plugin is stable enough, we can include your plugin as part of the official OMF release guide.
- Follow the same guidelines as modifying OMF code when come to code quality control.
- If your project seems to be short lived (as part of your study, for example), please notify us for the necessary shift of the ownership, simply, do not throw anything, they might still be useful for the us.
Gem creation and release
If you are not familiar with ruby's package system, this official guide http://guides.rubygems.org/ will certainly help. We provide a gem skeleton for you to start with:
Also, omf_rc_openflow gem mentioned earlier will be a good place to visit.