-
Notifications
You must be signed in to change notification settings - Fork 25
Contribution guidelines
This document is still being written and structured, and so it is subject to changes.
Development in the core repository should center around the following trees:
- Release snapshots (git tags in fact) of unchanging core code
- An ongoing master development branch with guarantees of code quality
- Multiple feature branches for unstable code development, with no guarantees
Tags will specify a frozen interface between core RF code and RFProxy implementations. Periodically, a new version of RouteFlow will be tagged. A tag will never be modified. RFProxy implementations can then base against a particular tag, and will always work with it.
Submissions to the master branch will be reviewed by a core team. Code will not be accepted here unless the community accepts the code quality (specific criteria will defined). Submitters are encouraged to keep patches small to assist code review.
New features will be developed separately by a submitter. This may be maintained in one of three ways based on the stability and quality of the code:
- On submitter’s fork (if development is particularly new or frequent)
- On core feature branch if the submitter does not wish to maintain the feature or wants/needs to work more closely (some student projects will fit in this case)
- On the master branch if the code has been reviewed, accepted and merged.
The core RouteFlow repository will be controlled by the core team. Controller repositories will be managed by the wider RouteFlow community. The wider group will have minimal barrier to entry, allowing new developers to create and directly modify RFProxy implementations without approval of the core team.
A tag is the version number of RouteFlow as a whole. This is managed by the core team, as a quality snapshot of the master branch at a specific time. Usually it will follow a X.Y versioning scheme. If a major bug needs fixing soon after release, this will follow a X.Y.Z versioning scheme.
-
X: Major architecture change -
Y: Minor design change/Feature release -
Z: Bugfixes Developers of RFProxy implementations should aim to target the implementation against a particularX.Yversion of RouteFlow core. The RFProtocol interface between these components may change between versions, or further functionality may be expected from later versions.
Pull requests should be regularly reviewed for merging into the master branch. As core team resources allow, the feature branches will also be reviewed and merged. Testing should always be done before merging. Periodically, as milestones are hit, or as interfaces change (e.g. RFProtocol), the master branch will be taken and tagged with a new version number. An announcement will be made on the RouteFlow mailing-list regarding the new version. This will allow the wider community to keep in sync with the core development.
This is primarily to ensure there are no regressions in functionality from one version to the next. Overall, patch-sets should be looked over to check for logical issues before merging into master. Reviewing should be done publicly on GitHub, by responding to either a Pull Request or on specific patches. Changes should also be tested before merging. Ideally we would later move towards an automated test system for independently verifying this.
RFProxy repositories must include a README being explicit about which version of the controller platform is being used (eg, Ryu v1.2) to minimise confusion. RFProxy repositories may include a copy of the controller platform. If this is included, the master branch should periodically synchronised with upstream development.
RFProxy implementations should include a branch or tag with the same MAJOR.MINOR version as the latest RouteFlow version. Branches/Tags that correspond with older RouteFlow versions are optional. When RFProxy has been ported to a new platform, this can be integrated with the core RouteFlow codebase by sending a request to the RouteFlow mailing-list or by opening a pull request on the core repository with the required changes.
Scripts in the main RouteFlow distribution will be responsible for automatically downloading and building the appropriate RFProxy implementation requested by the user, respecting version numbers.
Before performing some work on RouteFlow, it is recommended that developers send an email to the RouteFlow mailing-list or report an issue in GitHub to discuss the changes. This way, the community can give feedback on the approach. Final patch-sets should be sent as a pull-request on GitHub. Each patch should only make a single logical. Code tidy-ups should be separate from functional changes. Lots of small patches is preferred over sending one large patch. Pull requests to master should be tested by the submitter to ensure that there are no functionality regressions.