UnifiedViews Documentation

Downloads:

 

 

Skip to end of metadata
Go to start of metadata

Field guide for contributors

How to contribute?

Everybody who would like to contribute to the UnifiedViews repositories, has two basic options how to contribute:

1) Become an external contributor. To become an external contributor, you simply fork the UnifiedViews project at any time, prepare your contributions and create pull request on the proper repository. Then, before you contributions may be merged to the UnifiedViews project, you have to sign the Contribution Agreement. 

2) Become an internal contributor.  To  become an internal contributor, you have to sign the Contribution Agreement. Then you may become part of the internal development team and may contribute directly to the project repositories - most of your contributions will still go over pull requests, but you can also add trivial changes (bug fixing) directly to develop branch. 

Contribution Agreement must be prepared, signed, and submitted via email or regular post to ... TODO

Before you start to contribute any code, please read and use Coding Guidelines and prepare your environment correspondingly.

Should I become an external or internal contributor?  

Typically, when you start contributing to the code, you start as an external contributor. Later on, if contributing further, you may discuss with repository managers to become part of the internal team - to become internal contributor. The advantage of internal contributor is that his improvements are more quickly accepted and he may also commit trivial adjustments directly to the develop branch. 

Membership among internal development team must always be confirmed by one of the repository managers

 

For COMSODE.eu contributors: 

1) start feature branch which is based on develop branch (see below how you should work with gitflow), name it based on the github issue it solves. Every feature branch should solve some github issue. Every feature should have separated branch. Never it should happen that one feature branch is modifying more than one DPU. 
2) When done, publish the feature branch and send notice to toknap@gmail.com (sveto.krchnavy@eea.sk (project manager) in cc). 
3) I will review the code (or delegate the reviewing) and if ok, the issue in github is tagged as "approved"
4) If marked as "approved" (and please not earlier) you may merge the feature branch (git flow finish) to the develop branch 

Overview over repositories used

Github project used for developing UnifiedViews: https://github.com/UnifiedViews

The project is shared by EEA/CUNI/Semantic Web Company (SWC) developers. 

There are three repositories: 

Contributing to Core repository

Repository: https://github.com/UnifiedViews/Core

Description: Repository holding the implementation of the UnifiedViews - core features  + core plugins available in all distributions. 

Issue tracker: https://github.com/UnifiedViews/Core/issues. General rules for issue tracking must be enforced

By internal contributors, Branching and release policy must be enforced.

By external contributors, defined format of pull requests must be enforced. 

 

To get the working copy (for an internal contributor):

  1. Clone the repository
    1. git clone https://github.com/UnifiedViews/Core.git
  2. Checkout and switch to the develop branch
    1. git checkout -b develop origin/develop

 

Contributing to Plugins repository

Repository: https://github.com/UnifiedViews/Plugins 

Description: Repository holding the plugins for UnifiedViews tool

Issue tracker: https://github.com/UnifiedViews/Plugins/issuesGeneral rules for issue tracking must be enforced

By internal contributors, Branching and release policy must be enforced.

By external contributors, defined format of pull requests must be enforced. 

To get the working copy (for an internal contributor):

  1. Clone the repository
    1. git clone https://github.com/UnifiedViews/Plugins.git
  2. Checkout and switch to the develop branch
    1. git checkout -b develop origin/develop

 

General tutorial/guides/info for creating plugins: Creation of Plugins (DPUs)

Keep in mind that  plugins in this repository are publicly visible and created in a shared space for EEA/CUNI/SWC. 

Do not contribute to this repository if you are creating a plugin, which can be used only for a specific project's needs and you do not foresee any applicability in general case.

Every plugin has to define its license, its description, and version. Description must contain the contact to the author. If you change functionality of the plugin (or did change which may change the functionality) please change the version of the plugin correspondingly. 

If you are not sure whether to contribute to this repository, please discuss with repository managers.

 

 

Branching and release policy for internal contributors 

(Taken from http://nvie.com/posts/a-successful-git-branching-model/, where more details may be found)


All repositories contain two main branches with an infinite lifetime: 

  • master - the source code of HEAD always reflects a production-ready state.

  • develop - the source code of HEAD always reflects a state with the latest delivered development changes for the next release.

When contributing to the project, you must always create a temporal branch for you contribution. Such branch must be deleted when properly merged back to develop/master branches.

GitFlow

A tool (Git extension), which supports this branching and release policy, see http://danielkummer.github.io/git-flow-cheatsheet/ for details. 

You as an internal contributor should always use this git flow extension if possible, because it simplifies the proper use of the branching and release policy. 

For installation guide, please see http://danielkummer.github.io/git-flow-cheatsheet/#setup

 

Branches:

We distinguish the following types of branches. For each branch, we introduce:

1) who may create such branches

2) From which main branch (develop or master) the branch may be created

3) To which main branch (develop or master) the branch may be merged

We also introduce for each branch git flow command, which should be used. 

Feature branches 

Who may create such branches: Internal contributors, Repository managers

May branch off from: develop

Must merge back into: develop

Feature branches (or sometimes called topic branches) are used to develop new features for the upcoming or a distant future release. When starting development of a feature, the target release in which this feature will be incorporated may well be unknown at that point. The essence of a feature branch is that it exists as long as the feature is in development, but will eventually be merged back into develop (to definitely add the new feature to the upcoming release) or discarded (in case of a disappointing experiment).

Unless the feature branch is shared by more developers, feature branches typically exist in developer repos only, not in origin (it is not mandatory to push/publish feature branch into github repository). 

Guideline:

  1. Creates new feature branch feature/{featureName} based on the develop branch and switches to that branch 
    1. git flow feature start {featureName}
  2. (Optional) If more internal contributors should collaborate on the release, you need to publish the feature branch
    1. git flow feature publish {featureName}
  3. Work on that branch as needed
  4. Merges feature/{featureName} branch back to the develop branch, removes the feature branch, switches to develop branch ((warning) rebase shall not be used)
    1. git flow feature finish {featureName}

Release branches

Who may create such branches: repository managers. Internal contributors may only contribute to the release branched when invited, they may not create release branches

May branch off from: develop
Must merge back into: develop and master
 

Release branches support preparation of a new production release. They allow for last-minute dotting of i’s and crossing t’s. Furthermore, they allow for minor bug fixes and preparing meta-data for a release (version number, build dates, etc.). By doing all of this work on a release branch, the develop branch is cleared to receive features for the next big release. 

Adding large new features here is strictly prohibited. 

See more details here: Releasing & Hotfixing UnifiedViews

Hotfix branches

Who may create such branches: Internal contributors, repository managers

May branch off from: master
Must merge back into: develop and master
Branch naming convention: hotfix/{name}

Hotfix branches are very much like release branches in that they are also meant to prepare for a new production release, albeit unplanned. They arise from the necessity to act immediately upon an undesired state of a live production version. When a critical bug in a production version must be resolved immediately, a hotfix branch may be branched off from the corresponding tag on the master branch that marks the production version. 

See more details here: Releasing & Hotfixing UnifiedViews

Summary

 Summary of all types of introduced branches: 

 

 Summary overview of the git flow commands available: 

 

Format of pull requests for external contributors 

The description of your pull request should contain  #XXX, XXX is the issue number the pull request is relevant for. 

If you would like to implement more features, address more bugs, please prepare for each such feature/bug a separated pull request. 

General guidelines for Issues tracking 

Every repository has its own issue tracking (see below). We use github issue tracker. Both external and internal contributors may contribute to the issue tracker.

Github issue tracker has only 2 issue states (open and closed) so intermediate statuses have to be managed using labels. Releases are planed using Milestones.

For issues reporters:

When creating issues, please:

  • specify proper issue title that reflects description of the issue
  • specify steps to reproduce (always)
  • specify the tag (release version) of the master branch or commit of the develop branch on which the issue occurred (always)
  • provide screenshot to illustrate the problem (if possible)
  • provide the relevant part from the log (frontend.log, backend.log) (if possible)

These labels shall be also setup:

  • specify proper severity (always)
    • if the issues is a bug, use "severity: bug" label.
    • If the issue is an enhancement/new feature, use "severity: enhancement" label
    • if the issue is a support request, use "severity: question". Note: primarily, mailing list created for this purpose shall be used
  • specify the priority of the issue. ("priority: Urgent", "priority: High", "priority: Normal", "priority: Low")
    Note: the priority may be adjusted by the issue managers.

When the issues is done, you can browse the commits created as the issue was being solved. When the issues is ready for being tested by the issue reporter, it is denoted as "Test that" and assignee is switched back to the issues reporter.

For issue manager / release manager

Assignee: 

  • If you you know precisely who should be assigned, assign that person. Otherwise, please specify lead architect as an assignee.
  • If the issue is related to COMSODE project, please specify repository manager tomas-knap

Milestone

  • If you are release manager, specify the desired open milestone when the issue should be solved. Typically, you specify the milestone with the nearest deadline in the future.

Labels:

  • if necessary, you could adjust priority ("priority: Urgent", "priority: High", "priority: Normal", "priority: Low")
  • if the issue has label labels "status: resolved" and "resolution: fixed" you can approve finish the feature.
  • if the feature is finished (merged into develop), you shall setup "status: ready for test"
    • Milestone have to be defined in this stage
    • reporter shall test the issue
  • if the feature is tested and finished, you shall setup "status: tested" and issue could be closed.

For internal contributors solving the issues:

Rules to select issue to be solved:

  • Solve only issues, which are assigned to you.
  • Solve the issues strictly based on the priority.
  • Always solve only issues for the nearest milestone.
  • When you start solving the issue, use the branching and release policy in this document.
  • When creating new branch solving the issue, the name of the branch should involve the issue number. 
  • When you commit anything to the created branch, always specify a commit message, which must contain the issue it is related to (if there is such issue) by specifying #XXX in the commit message, XXX is the issue number.
  • Feature can be finished (merged into develop) only if approved by issue manager
  • Before finishing the issue, it is advised to merge develop branch into feature branch to solve conflicts; mainly in case when conflicts are expected, for example many commits in develop branch available from feature branch start..

Labels:

  • When you are done with the issue - issue was implemented and tested
    • setup labels "status: resolved" and "resolution: fixed".

For external contributors solving the issues: 

Pull requests are intended to be used for external contributors.

  • The description of your pull request should contain  #XXX, XXX is the issue number the pull request is relevant for.  


Convention on naming the artifacts created by maven:

When you build certain release (master branch with the given tag - version), the names of the created artifacts contain the tag (version), e.g., commons-app-1.0.0.jar

When you build the develop branch (latest commit), the names of the created artifacts contains the information about the next planned major tag (version) and information that it is a working version (SNAPSHOT), e.g., commons-app-2.0-SNAPSHOT.jar, in case that the latest master version is >= 1.0.0 < 2.0.0 .  

Tests

 

The tests are located in java's common place. e.g /src/main/test/java/yourpackage

The tests are divided into two types:

the unit tests - are typical junit test, they don't need any external system 

the integration tests - are the tests which need some external system. There are distinguished by a their name. A test needs to ends with: SysTest. e.g. VirtuosoSysTest.java.  Run by "mvn -PSYSTESTS test"


 

 

  • No labels