Developers Frequently Asked Questions

Developing JSAGA engine

1. What are the pre-requisites for building JSAGA entirely ?
2. How to build JSAGA from source ?
3. How to release JSAGA ?
4. How to deploy a snapshot of JSAGA ?
5. How to test web site generation without deploying it ?
6. How to configure apache for maven repository ?

GIT

1. How to merge a contribution into the reference repository ?
2. How to merge a branch without detailed history ?
3. How to apply and merge a patch ?
4. How to apply and merge a conflicting patch ?
5. How to rebase a published branch
6. How to fix a small problem (e.g. typo in generated web page) in a release, without creating a new release ?

Developing JSAGA engine

What are the pre-requisites for building JSAGA entirely ?

• Install JDK 1.6 (or above)
• Install Maven 3.0.4 (or above)
• Optional: releasing JSAGA requires SSH to be installed
• Optional: some adaptors requires gcc compiler to be installed (these adaptors must either be built on both windows and linux platforms, or you can build everything from windows by installing cygwin, cross-compiler for linux and JNI header files for linux)

[top]

---

How to build JSAGA from source ?

• Install and configure SSH according to these instructions
• Download bootstrap POM file
• Build from latest source code

  mvn scm:bootstrap

  Or build an old release

  TAG={release_tag}
  mvn scm:bootstrap -DscmVersionType=tag -DscmVersion=$TAG -Dgoals=deploy,site-deploy

[top]

---

How to release JSAGA ?

• Update the release notes (jsaga-installer/src/changes/changes.xml)
  
  
• Update the "Previous releases" section in the download page (jsaga-installer/src/site/sxl/download.xsl)
  
  
• Update from GIT and select the branch "master"

  git pull
  git checkout master

• From a ccdevli host, run:

  mvn -f pom-unreleased.xml deploy
  
  mvn release:prepare
  mvn release:perform
  

  At this point, if you get an error like:

  [INFO] [ERROR] Failed to execute goal org.apache.maven.plugins:maven-site-plugin:3.3:site (default-site) on project saga-api-test: 
  failed to get report for org.apache.maven.plugins:maven-javadoc-plugin: Failed to execute goal on project jsaga-adaptor-srm: 
  Could not resolve dependencies for project fr.in2p3.jsaga.adaptor:jsaga-adaptor-srm:jar:1.0.0: The following artifacts could not 
  be resolved: fr.in2p3.jsaga.adaptor:jsaga-adaptor-voms:jar:1.0.0, fr.in2p3.jsaga.adaptor:jsaga-adaptor-globus:jar:1.0.0, 
  fr.in2p3.jsaga:jsaga-adaptoritf:jar:1.0.0, fr.in2p3.jsaga:jsaga-engine:jar:1.0.0: 
  Could not find artifact fr.in2p3.jsaga.adaptor:jsaga-adaptor-voms:jar:1.0.0 
  

  You have to manually install release artifacts in your local repository:

  cd build/checkout
  mvn install
  cd -
  mvn release:perform
  

• Change the symbolic link latest-release on the web server
• Upgrade snapshot version in:
  • saga-api/pom.xml:parent
  • maven/maven-archetype-jsaga/resources/archetype-resources/pom.xml:parent
• Close version in https://forge.in2p3.fr/projects/jsaga/settings/versions

[top]

---

How to deploy a snapshot of JSAGA ?

• Update from GIT and select the branch to build

  git pull
  git checkout <yourBranch>

• From a ccdevli host, run:

  mvn -f pom-unreleased.xml deploy
  
  mvn deploy site-deploy

• Change the symbolic link dev on the web server

[top]

---

How to test web site generation without deploying it ?

From a ccdevli host, run:

mvn site-deploy -P local

[top]

---

How to configure apache for maven repository ?

Create file .htaccess with the following content:

Options +Indexes
IndexOptions +NameWidth=* +DescriptionWidth=*
AddDescription " " .md5
AddDescription " " .sha1
AddDescription "Tarball distribution" .tar.gz
AddDescription "ZIP distribution" .zip
AddDescription "GUI Installer" .jar

[top]

GIT

How to merge a contribution into the reference repository ?

# Get branch name
git ls-remote ssh://git.in2p3.fr/jsaga-contrib

# Pull contribution in branch "mergedBranch"
git checkout -b mergedBranch master
git pull ssh://git.in2p3.fr/jsaga-contrib <branch name>

# Merge it in branch "master"
git checkout master
git merge mergedBranch

# Cleanup
git branch -d mergedBranch

[top]

---

How to merge a branch without detailed history ?

Use unix diff instead of "git format-patch":

# Update local repository
git pull

# Create patch
git checkout workingBranch
git diff origin/master > mydiff.patch

# Apply patch
git checkout -b mergedBranch master
git apply --stat myDiff.patch
git apply --check myDiff.patch
git apply myDiff.patch

# Merge
git checkout master
git merge mergedBranch

# Delete remote and local branches
git push origin :workingBranch
git branch -D workingBranch
git branch -d mergedBranch
git branch -al

WARNING: This does not work if some binary files have been modified.

[top]

---

How to apply and merge a patch ?

Use "git apply-patch" or "git am":

# Update local repository
git pull

# Apply patch
git checkout -b mergedBranch master
git am --ignore-space-change --ignore-whitespace patch.mbox

# Check changes with IDE (GIT -> Push Active Branches...)

# Merge
git checkout master
git merge mergedBranch

# Delete local branch
git branch -d mergedBranch
git branch -al

[top]

---

How to apply and merge a conflicting patch ?

Checkout a non-conflicting (past) version of branch 'master':

$ git rev-list -n 1 --before="2011-12-27 00:00" master
e0ad6b79cc64d5720a9754231146438ceb1ddaf3

$ git checkout -b new_branch_name e0ad6b79cc64d5720a9754231146438ceb1ddaf3
HEAD is now at e0ad6b7... log message of patch

• Apply patch (see above)
• Interactively rebase 'new_branch_name' onto 'master'
• Configure 'master' as the tracked branch
• Push active changes

[top]

---

How to rebase a published branch

Note: you should not rebase a branch if it has been modified by other contributors.

# Update local repository
git pull

git checkout workingBranch
# perform interactive rebasing onto branch "master"
# in case of conflict, add the conflicting file(s) to GIT (but do not commit them)

# replace old branch (remote) with rebased branch (local)
git push origin :workingBranch
git push workingBranch
               

[top]

---

How to fix a small problem (e.g. typo in generated web page) in a release, without creating a new release ?

# Update the release tag
git checkout <release_tag>
git show
git checkout -b <release_tag>
git show
vim pom.xml
git diff
git commit -m 'tag bis' pom.xml
git tag -f <release_tag>
git push origin --tags
git branch -D <release_tag>
               

DO NOT FORGET TO DO THE SAME FIX IN BRANCH 'master' ! DO NOT FORGET TO FETCH TAGS (git fetch --tags) ON ALL REPOSITORY CLONES !

[top]