DEVELOPING

   1 Working on Jim
   2 ==============
   3
   4 Jim's sources are kept in Git Version Control System. Global repository of
   5 Jim project is placed on this Web site:
   6
   7         http://repo.or.cz/w/jimtcl.git
   8
   9 There are two ways of contributing to Jim project. First is suited for
  10 one-time fixes and small corrections. The second is more appropriate
  11 for long-term contributors interested in Jim internals.
  12
  13 Small changes
  14 =============
  15
  16 For small modifications, procedure of preparing a traditional 'patch'
  17 is enough. In order to prepare a patch, you first have to obtain the
  18 most recent copy of Jim Tcl. This can be done with following command:
  19
  20         git clone http://repo.or.cz/r/jimtcl.git
  21
  22 After entering newly created directory you can easily correct/fix/modify
  23 files. Once finished, patch can be easily generated:
  24
  25         git diff > my_patch_fixing_x_y.patch
  26
  27 If working without Git system, you'll have to backup files first, modify
  28 the original files and obtain a patch manually:
  29
  30         cp jim.c jim.c.ORIGINAL
  31
  32         [...] <- modifications go here
  33
  34         diff -u jim.c.ORIGINAL jim.c > my_patch_fixing_z.patch
  35
  36 Bigger changes
  37 ==============
  38
  39 In order to help extending and correcting Jim in a long term basis, one
  40 needs to create separate fork of Jim project and maintain his changes in a
  41 separate copy of a repository.
  42
  43 By visiting this site, you'll have a chance to fork a project. This can
  44 be easily done with "fork" link. Form that will show up next refers to
  45 the project that is about to be started. The only thing that has to be
  46 taken care of is the project mode -- it should be "push mode".
  47
  48 Once the project is created one must add a user that will actually
  49 start committing new files to the repo. It can also be done through the
  50 WWW interface, so nothing more is necessary.
  51
  52 Once finished with setting up a project on the WWW panel, one can
  53 start playing with actual import of the files. In order to obtain copy
  54 of Jim sources, we have to clone the repository:
  55
  56         git clone http://repo.or.cz/r/jimtcl.git
  57
  58 Now, we must push fresh copy of Jim to your project URL:
  59
  60         git push <URL> master
  61
  62 So for example for me it was:
  63
  64         git push ssh://repo.or.cz/srv/git/jimtcl/wkoszek.git master
  65
  66 In order to add file we type "git add <file>".  For remove, we do "git rm
  67 <file>".  To remove all local changes that aren't in a repository you do "git
  68 reset --hard HEAD".  Once inserted, files have to be committed with "git commit
  69 -a".  Once done with commits for today, "git push" can be used to propagate
  70 changes from your local disk to the remote repository.
  71
  72 Right now you can verify whether this works by trying to clone your
  73 project's repository somewhere else, this time using anonymous HTTP
  74 access:
  75
  76         git clone http://repo.or.cz/r/jimtcl/wkoszek.git
  77
  78 Review, testing and publishing
  79 ==============================
  80
  81 Notification of work that can be considered finished is more than welcome on
  82 Jim-devel mailing list:
  83
  84         http://jim.tcl.tk:8080/cgi-bin/mailman/listinfo/jim-devel
  85
  86 Patches prepared with the procedures presented above are welcome. Before
  87 submitting patches, you can verify that your changes didn't bring any
  88 regressions to the Jim. In order to do so, sample regression tests have
  89 been implemented. You can execute them by typing:
  90
  91         make test
  92
  93 All tests should succeed.