Changes between Initial Version and Version 1 of OMF/OMF60/1Developer/2Contributing

May 17, 2019, 3:13:37 PM (19 months ago)



  • OMF/OMF60/1Developer/2Contributing

    v1 v1  
     1== Contribution Guide ==
     3=== Getting the source ===
     4From github:
     6git clone
     9=== Modifying the source ===
     10Feel 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.
     12=== Readable code ===
     13The following ruby coding style will be used:
     17Please make sure your files do not contain trailing white spaces. Most editors and IDEs can be configured to do it automatically.
     19If you got existing code that could contain trailing white spaces, simply run this command in root directory of the project:
     21find . -not \( -name .git -prune \) -type f -print0 | xargs -0 sed -i "s/[[:space:]]*$//"
     23and then commit the change.
     25=== Semantic versioning ===
     26Choose git tag name according to semantic versioning rules:
     28=== Useful documentation ===
     29Yard is used for auto generating OMF code documentation. Refer to [ this guide] for details.
     31=== Meaningful commit message ===
     32Please provide a meaningful commit message for each commit.
     34The commit message should be formatted properly:
     36Capitalized, short (50 chars or less) summary
     38More detailed explanatory text, if necessary.
     39In some contexts, the first line is treated as the subject of an email and the rest of the text as the body.
     40The blank line separating the summary from the body is critical (unless you omit the body entirely);
     41tools like rebase can get confused if you run the two together.
     43You could modify commit message if you realised you made a mistake after committed.
     45git commit --amend
     48=== Test your changes ===
     49We 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.
     51You can examine test folder under components to find out how test files are organised.
     53You can execute these tests manually by issuing rake command inside components directory. For example:
     55cd omf_common; rake
     57For more information regarding MiniTest, please go to the official site:
     61Eventmachine in minitest
     63To test asynchronous eventmachine based code, refer to this minitest pluging:
     67Sign your commit
     68You could sign your commit & tag using -s option in git.
     70git commit -s
     71git tag -s
     72Share your change
     73Your changes & hacks made locally could be useful for other OMF users and OMF project in general. Please share your changes with us.
     75Using git
     76This git tutorial will give you plenty of tips to get started if you need some help regarding git.
     80Set up git identity
     81If 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:
     83git config --global "your name"
     84git config --global "your email address"
     85See git config -h for all options.
     87The @--global@ sets these parameters for all your Git repos. You can limit this to the current repo by removing this option.
     89These options could also be set up via editing .gitconfig file.
     91Announce your changes
     92When you are satisfied with your changes, you can provide them to us so we can review them and integrate them into the main tree.
     94Please create an issue in our issue tracking system so it can tracked.
     96Then you have these options to provide us the access to your changes
     98Prepare a git patch and send it to
     99Prepare a git patch and attach to the issue you created.
     100Send a pull request to
     101Send a email to, 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)
     102Patch creation
     103The first two options need you to create patches from the Git branch containing your changes.
     105The best way to do this is with git format-patch to have export them in a suitable format:
     107git format-patch origin/master..HEAD # Assuming you started working from origin/master
     108Pull request
     109If 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.
     111git request-pull origin/master http://url/of/repo # Assuming you started working from origin/master
     112Manage your own repository
     113The 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.
     115Please consider the following:
     117Start such repository only if you think it won't be necessary for OMF core system to include such features.
     118Once your plugin is stable enough, we can include your plugin as part of the official OMF release guide.
     119Follow the same guidelines as modifying OMF code when come to code quality control.
     120If 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.
     121Gem creation and release
     122If you are not familiar with ruby's package system, this official guide will certainly help. We provide a gem skeleton for you to start with:
     126Also, omf_rc_openflow gem mentioned earlier will be a good place to visit.