dev/git/Git_Simple_Write_Procedure.rst

   1 Contributing to the SALOME project with Git
   2 ===========================================
   3
   4 This short document indicates the process to be followed by anyone wishing to contribute code to the SALOME project using Git. If you read this document, you should have received the credentials allowing you to write your changes into the central repository.
   5
   6 Get your copy of the central repository
   7 ---------------------------------------
   8
   9 1. Clone the latest version of the repository for the module you want to modify::
  10
  11     git clone ssh://<proper-final-url>
  12
  13
  14   This retrieves a local copy of the module's repository onto your machine.
  15
  16 2. If you were already given a branch name to work with, you can simply retrieve it and start working::
  17
  18     git checkout -b <branch_name> origin/<branch_name>
  19
  20
  21   This creates a local copy of the branch, and sets it up to be a copy of the remote branch on the central server. You can jump directly to the next section (Workflow) telling how to commit and publish changes.
  22
  23 3. Otherwise you need to create and publish a new branch in which you will do your changes (you are not allowed to commit changes directly into the main branch 'master'). First create the local version of the new branch::
  24
  25     git checkout master
  26     git checkout -b <xyz/short_desc>
  27
  28
  29   where <xyz> are you initials (John Smith gives 'jsm') and <short_desc> is a small string indicating what changes will be made. For example::
  30
  31     jsm/new_viewer
  32
  33
  34   The last command creates the branch locally, and update your working directory (i.e. the source code) to match this branch: every change and commit you make from now on will be stored in this branch.
  35
  36 4. Publish your branch to the central repository for the first time::
  37
  38     git push -u origin <xyz/short_desc>
  39
  40
  41   The option "-u" ensure your local branch will be easily synchronized with the remote copy on the central server. With older versions of Git you might have to execute the above in two steps::
  42
  43     git push origin <xyz/short_desc>
  44     git branch -u origin/<xyz/short_desc>
  45
  46
  47 Workflow
  48 --------
  49
  50 1. If you didn't update your local copy for a while, update it with the following command. This retrieves from the central server all changes published by other people working on your branch. This step is not necessary if you just initialized your repository as described above::
  51
  52     git checkout <xyz/short_desc>
  53     git pull
  54
  55 2. Do your changes, compile.
  56 3. Perform the appropriate tests to ensure the changes work as expected.
  57 4. If you create a new source file, you need to make Git aware of it::
  58
  59     git add <path/to/new/file>
  60
  61 5. When everything is ready you can commit all your changes into your local repository::
  62
  63     git commit -a
  64
  65   The "-a" option tells Git to automatically take all the changes you made for the current commit. You will be asked to enter a commit message. Please, *please*, write something sensible. A good format is::
  66
  67     GLViewer: enhance ergonomy of the 3D view
  68
  69     User can now zoom in and out using the mouse wheel.
  70     Corresponding keyboard shortcuts have also been added.
  71
  72   i.e. a first short line containing the class/code entity that was modified, and a short description of the change. Then a blank line, and a long description of the change. Remember that this message is mainly for other people to understand quickly what you did.
  73
  74
  75   At this point, the changes are just saved in your local repository. You can still revert them, amend the commits, and perform any other operation that re-writes the local history.
  76
  77 6. Once you feel everything is ready to be seen by the rest of the world, you can publish your work. The first step is to synchronize again with any potential change published in your branch on the central repository. This can happen while you were working locally::
  78
  79     git pull
  80
  81 7. At this stage, two situations can arise. If nothing (or some unrelated stuff to your work) happened on the central repository, Git will not complain (or potentially do an automatic merge). You can inspect the latest changes committed by others with commands like::
  82
  83     git log
  84     gitk
  85
  86   If you notice changes made by others that can affect what you're working on, it might be a good idea to recompile and retest what you have done, even if Git did the merge automatically. Once you are happy, you can directly go to step 9.
  87
  88 8. Conflict resolution. If a message saying "CONFLICT: automatic merge FAILED" appears, it means that some changes made by others are in conflict with what you committed locally (typically happens when the other person modified a file that you also changed). In that case, you need to integrate both changes: edit the file so that both changes work together (or so that only one version is retained). Conflicts are marked in the file like this::
  89
  90     <<<<<<< HEAD:mergetest
  91     This is my third line
  92     =======
  93     This is a fourth line I am adding
  94     >>>>>>> 4e2b407f501b68f8588aa645acafffa0224b9b78:mergetest
  95
  96   Once you resolved the conflict, re-compiled and re-tested the code, you need to tell Git that the file is no more in conflict::
  97
  98     git add <the_file>
  99
 100   You can then finish the merge operation by committing the whole thing::
 101
 102     git commit -a
 103
 104   In this peculiar case (conflict resolution) you will see that Git offers you a default message (merge message). You can complete this message to indicate for example how the conflict was solved.
 105
 106 9. When all conflicts are solved (and the code has been compiled and tested again if needed) you can finally publish your work to the central repository::
 107
 108     git push
 109
 110   This makes your changes visible to others.
 111
 112 10. Once all your changes have been committed (potentially several commits) and you feel your modification is ready to be integrated in the main development line (i.e. to be considered for the next release), you can notify an administrator of the project to ask for your changes to be merged in the *master* branch.
 113
 114
 115 Special notes for EDF users
 116 ---------------------------
 117
 118 Working with YAMM
 119 ^^^^^^^^^^^^^^^^^
 120
 121 YAMM is the tool used at EDF to build SALOME platform. Among other things, it
 122 can automatically fetch and compile SALOME sources. If you just need a
 123 read-only access to Salome sources from a standard EDF computer (Calibre 7),
 124 you just need to run YAMM with no specific configuration. The sources will be
 125 fetched automatically and the compilation will proceed as usual.
 126
 127 If you need to develop and push changes in Salome sources, follow those steps:
 128
 129 1. Make sure you have a write access to Salome sources. If not, ask your project
 130    manager who will forward your request to Salome repository administrator.
 131
 132 2. Save your credentials on your local computer. For that, edit the file
 133    $HOME/.netrc (create it if it doesn't exist), and add the following lines::
 134
 135     machine git.salome-platform.org
 136     login mylogin
 137     password mypassword
 138
 139   Replace "mylogin" by your login on Salome repository and "mypassword" by
 140   your password on the repository. The password here is in clear, so make sure
 141   this file is only readable by yourself::
 142
 143     $ chmod 600 ~/.netrc
 144
 145 3. Disable SSL verification for git. For that, edit the file $HOME/.bashrc and
 146    add the following line::
 147
 148     export GIT_SSL_NO_VERIFY=true
 149
 150    Alternatively, if you have a root access on your computer, you can install
 151    the right certificate and allow SSL verification. How to do so is out of the
 152    scope of this guide.
 153
 154 4. Configure YAMM to use your login to fetch Salome sources, for instance by
 155    adding the following lines in your YAMM project configuration file::
 156
 157     # Configure the username for SALOME modules
 158     project.options.set_global_option("occ_username", "mylogin")
 159
 160     # Eventually configure the username for other modules
 161     project.options.set_software_option("EFICAS", "occ_username", "myeficaslogin")
 162     project.options.set_software_option("EFICASV1", "occ_username", "myeficaslogin")
 163
 164 5. Launch YAMM to fetch and compile all Salome sources
 165
 166 6. Go to the directory containing the sources of the module you need to develop
 167    (for instance ~/salome/V7_main/modules/src/KERNEL).
 168
 169 7. Create a new development branch, following the instructions in the previous
 170    section. This development branch MUST track a remote branch so that the future
 171    updates work properly.
 172
 173 8. Edit your YAMM project to specify that you work on a new development branch,
 174    for instance by adding the following lines::
 175
 176     softwares_user_version = {}
 177     softwares_user_version["KERNEL"] = "rbe/my-new-development"
 178     salome_project.options.set_global_option("softwares_user_version", softwares_user_version)
 179
 180 9. You can then develop the new requested features and commit them. Each time
 181    you run YAMM, it will merge the remote tracking branch in your local branch.
 182    When you are done, you can push your developments on the remote repository and
 183    ask an integrator to integrate them in the master branch, as explained in the
 184    previous section.
 185
 186 Proxy issues
 187 ^^^^^^^^^^^^
 188
 189 YAMM automatically configures the proxy settings for a standard usage at EDF
 190 (Calibre 7 computer inside EDF network). In this case, you have nothing special
 191 to do to access Salome repository. But if you are not in this standard
 192 configuration, the following tips may be useful.
 193
 194 1. Non-standard computers: You have to authentify yourself to the proxy in order
 195    to fetch Salome sources. For that, get the script edf-proxy-agent-cli
 196    (available on every Calibre 7 computer in /usr/bin) that can be launched as a
 197    daemon with -d option. Launch this script manually and type your SESAME
 198    username and password (it must be done each time you log on your computer).
 199    Further accesses to Salome repository should work properly.
 200
 201 2. Computers outside EDF network: Set the variable "git_config_proxy" in your
 202    YAMM project configuration to False in order to deactivate proxy usage::
 203
 204     salome_project.options.set_global_option("git_config_proxy", False)
 205
 206   If your computer is a laptop that is sometimes used inside EDF network and
 207   sometimes outside, configure the proxy manually by adding those lines to your
 208   ~/.bashrc file::
 209
 210     export http_proxy=http://proxypac.edf.fr:3128
 211     export https_proxy=http://proxypac.edf.fr:3128
 212     export no_proxy="localhost,.edf.fr"
 213
 214   This configuration will work inside EDF network. Simply comment those three
 215   lines when you use YAMM outside EDF network.