wiki:ProvideFix

Version 30 (modified by pbaumann, 3 months ago) (diff)

--

How To Provide A Fix

You developed a fix or some new functionality? We are grateful for your contribution.

Of course we like any useful information, but best (and fastest) for inclusion is to be in sync with our development tools. The following details are provided to help in this respect.

  1. All our development is in Linux. Please consider this for your code.
  2. We use git as version management tool, so you may want do do that too. Check out from the repository using:
    $ git clone git://rasdaman.org/rasdaman.git
    $ git config --global user.name "Name Surname"
    $ git config --global user.email my_email@address.xyz
    
  3. rasdaman must be configured and compiled with --enable-strict to make sure that your patch doesn't introduce new warnings.
  4. After ensuring the tests are successful (see RasdamanTestSuites), stage and commit your changes (whereby NNNN indicates the number of the ticket that is fixed with this patch):
    $ git add <file1> <file2> <dir1/> <dir2>/*.java ...
    $ git commit -m "ticket:NNNN My brief explanation of the patch"
    
  5. Prepare your patch package through:
    $ git format-patch -n 
    
    where n is the number of last commits that you want to create patch files for.
  6. Upload your patch file (or a .tar.gz archive in case of several files) using Patch Manager. You will have to accept the Contributor Agreement. Without your stated consent we unfortunately cannot accept it, due to legal reasons.

Git useful resources

For more help on git with see attachment or online book.

For info on git conflicts see Handling and Avoiding Conflicts in Git or, for a quick resolve conflict by discarding any local changes, this StackOverflow answer.

Linus Torvalds' suggestions on merging and rebasing : link.

Further tips (use 'Git*' naming rule for new pages):

Basic git for working on tickets

It is suggested to create a branch in your local working copy of the rasdaman git repo for each ticket/fix, then you will not mix up patches. (e.g: ticket:1450 -> branch_ticket_1450, ticket:1451 -> branch_ticket_1451)

Prerequisites

  1. Checkout the newest source code from repository (e.g: your cloned directory is: /home/rasdaman/rasdaman and you are in this directory and open Linux Terminal window)
       $ pwd
       /home/rasdaman/rasdaman
    
  2. List the branches in your local repository
       $ git branch
    
  3. Switch to branch master - as this branch is the canonical branch for Rasdaman remote repository
       
       $ git checkout master
    
  4. Pull the newest patches if possible from remote repository (rasdaman.org) to your local repository
       $ git pull
    

Create new local branch for ticket

Create new branch from master branch which has been updated to newest patches before

   $ git checkout -b "branch_name" (e.g: git checkout -b "branch_ticket_1451")
   $ git branch (to check your current branch)
   you will see you are in branch_ticket_1451

Work and commit the ticket fixes on this branch

  1. So you changed some file in source code directory (e.g: file1.java, file2.cc,...) and you want to create a commit
       $ git add file1.java
       $ git add file2.cc
       NOTE: or if you all to stage all files ($git add .), but be extremely careful with this
    
  1. Now you are ready to commit a patch from staged files (file1.java, file2.cc,...)
       $ git commit -m "ticket:1451 - fix some stuff"
       Check your commit is done (you will see your commit at the top of the log)
       $ git log 
    
  2. And create a patch from the commit (a patch is a file .patch which is created from your last commit (-1))
       $ git format-patch -1
       (or arc diff for code review)
    
  3. You finish with this branch by uploading the patch to Patch Manager http://rasdaman.org/patchmanager and switch to other ticket by creating new branch as in Step 2.

Switch between pending patches

E.g you finished one ticket on branch_ticket_1450 and upload to Patch Manager but the patch is rejected and need to be updated, meanwhile you are working on branch_ticket_1460.

  1. First, stage everything you are doing on branch_ticket_1460 (NOTE: if you don't want to create a temporary commit, you can just stash everything in current branch)
      $ git add --all .
    
  2. Then commit it as your pending patch on this branch
      $ git commit -m "ticket_1460: pending stuffs"
    
  3. Check if current branch is clear
      $ git status
      (it should report: "nothing to commit, working directory clean")
    
  4. Now switch to your failure patch (e.g: branch_ticket_1450)
      $ git checkout branch_ticket_1450
    
  5. Fix some issues here (by changing source files or add more files...). Follow the process in the [TODO Step 3] (stage new/modified files)
      $ git add <file 1> <file 2> ...
    
  6. Commit it without changing the ticket's title
      $ git commit --amend --no-edit
    
  7. Create a patch from the updated commit
      $ git format-patch -1
      (or arc diff for code review)
    
  8. And upload it again to Patch Manager
  9. Finally, you can switch back to your pending branch (e.g: on branch_ticket_1460)
      $ git checkout branch_ticket_1460
    

Apply your patches between branches

E.g you have 1 commit in branch_ticket_1450 and 1 commit in branch_ticket_1460) then you want to add this patch to branch_ticket_1460)

  1. Check current branch
       $ git branch (it should be branch_ticket_1450)
    
  2. Create a patch (file) from the last commit
       $ git format-patch -1
       (it will create a file, such as: "0001-ticket-1450-fix-some-issues.patch")
    
  3. Switch to other branch
       $ git checkout branch_ticket_1460
    
  4. Apply your patch from branch_ticket_1450
       $ git am -3  0001-ticket-1451-fix-some-issues.patch
    
  5. Check your newest patch (if the patch is applied successfully)
       $ git log
    

If a patch cannot be applied

I.e. you made changes on files which the patch also changes, so you have to merge it manually.

   $ git am -3 0001-ticket-1450-fix-some-issues.patch
   # The patch is not applied, some conflict will show here
  1. Please follow our own git conflict resolution guide, or Steps 3 to 7 of this resolving merge conflicts guide.
  2. Finally, you confirm the conflicts were resolved
       $ git am --resolved
    
  3. Check your patch from branch_ticket_1450 is now the last patch in branch_ticket_1460
       $git status
    

Attachments (1)

Download all attachments as: .zip