Child pages
  • Grouper developers coding standards
Skip to end of metadata
Go to start of metadata


We request that Grouper developers adhere to these standards:

Source control

  • Master is the dev branch.  If a new release was just cut, master might be the current release.  
  • Once work is needed on the next release a branch will be created.  
  • Branch names must follow the convention: GROUPER_2_3_0
  • Commits on released branches should only be made when a patch will be made. 
    After patch is made, tag the branch with this convention: grouper_X_Y_Z-aWW-uV-wU-pT e.g. grouper_2_4_0-a21-u9-w2-p2

    (master) $ git tag grouper_2_4_0-a25-u11-w2-p2
    (master) $ git push --tags
  • When committing (pull request or direct commit), you should have one JIRA associated with the commit.  

    GRP-1279: grouper installer should set sql logging to on so we can see progress of DDL on install or upgrade
     
    If there are more commits on the same issue, number them:
     
    GRP-1279: grouper installer should set sql logging to on so we can see progress of DDL on install or upgrade (commit 2)
    GRP-1279: grouper installer should set sql logging to on so we can see progress of DDL on install or upgrade (commit 3)
  • Every commit must have a unique comment (from all other commits).  This is so we can go back and see what hasnt been merged
  • Every commit in a non-master branch that should be merged forward must be cherry picked by the developer into all newer branches including master at the time of the commit
  • Pull requests must be on a recent pull of the branch the request is destined for so there are no conflicts
  • All new/edited junit tests should be included in patches (CH I think we need to change the installer to make this happen, its not that simple...)

Git Tips

Developers must create a separate (local) branch for a specific feature if a commit is not for an immediate patch.  That dev local branch should be named something like: GRP-1966-ui-visualization,  During development, multiple interim commits can be made and then squashed into a single commit for the main branch. Before merging to the main branch, switch back to the main branch, do a git pull to get the latest commits made by others. Then, switch back to the feature branch and do a rebase from the main branch. This makes your code apply to the main branch HEAD, rather than the historical commit where your branch started. The rebase changes the start of your branch to the main branch HEAD, and then replays all of your feature commits on top of it. If there are any merge conflicts, you will discover them now instead of later when trying to merge your feature. You can also test this updated code, to ensure it works before committing it to the main branch.

# Get the latest main branch code before starting the feature
(master) $ git pull
(master) $ git checkout -b grp-1279
(grp-1279) #do work, make commits
(grp-1279) #squash multiple commits together to a single new commit; e.g. here merge
(grp-1279) #the last two commits by changing all but the first commit
(grp-1279) #from "pick" to either "squash" (retain message) or "fixup" (ignore message)
(grp-1279) $ git rebase -i HEAD~~
(grp-1279) $ git checkout master
(master) #get any new commits
(master) $ git pull
(master) #if any new commits, go back to the feature branch and rebase
(master) $ git checkout grp-1279
(grp-1279) $ git rebase master
(grp-1279) #Retest. Fix any conflicts that occurred during the rebase. Then continue below
(grp-1279) $ git checkout master
(master) #merge should be a clean fast-forward merge
(master) $ git merge grp-1279
(master) $ git push
(master) #the branch is merged, can delete it now
(master) $ git branch -d grp-1279


Java

  • There is are eclipse formatting and prefs files in grouper/misc/eclipse
  • Never use tabs, only 2 spaces
  • Use curlies always e.g. for loops and if statements
  • Try to be explicit in naming classes and variables, try not to abbreviate
    • If a field or variable can be named the same as its type it might make things more clear or easier to read later.
    • e.g. if the type is "GrouperAttestationAttribute", maybe name it "grouperAttestationAttribute" instead of just "attribute"
  • Comment a lot
  • Always have javadoc
  • For new code don't commit if there are warnings in eclipse
  • Generally we use unchecked exceptions
  • Keep things backwards compatible generally, deprecate if needed

UI

  • Try not to use javascript, use the ajax API to write logic in Java and views in JSP


JIRA


See also