[a88b18]: README.developers-howto Maximize Restore History

Download this file

README.developers-howto    201 lines (119 with data), 5.9 kB

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
  Maxima project Git / build system HOWTO


  1  General

      Makefile.am is the file to modify, NOT Makefile
      (Makefile is generated automatically from Makefile.am)

      "make install" catches Makefile problems
      that are not detected by "make" alone

      Adding / removing files often leads to Makefile problems

      To update your repository, execute
      git pull  # assuming origin/master points to the SF Maxima repo

      Workflow with Git:
      git pull                      # update your repo
      git checkout master           # work off master
      git checkout -b scratch-pad   # create a working branch
      <do development, tests, commits, then, once satisfied...>
      git checkout master           # put yourself on master branch
      git pull                      # update your repo, again
      git merge scratch-pad         # merge development work into master
      git push origin master        # push to SF Maxima repo

      BE SURE NOT TO PUSH YOUR SCRATCH-PAD!

  2  Renaming something in Git

      --  Create a scratch/development branch as in 1.
  
      --  git mv X Y
          This moves X to Y and preserves the history.
	  Like any other change, this needs to be committed
	  as a separate step.

  3  Adding / removing a file in maxima/src

      --  Create a scratch/development branch as in 1.
  
      --  Add new file X, then execute
          git add X; git commit -m 'Message' -- X

      --  Remove old file X
          git rm X
          Then execute "git commit" as above

      --  Add / remove file name from maxima/src/Makefile.am

      --  Add / remove file name from maxima/src/*-depends.mk

          NOTE: There are several *-depends.mk files. These are
          theoretically updated automatically but to the best
          of my knowledge it is necessary to fix them by hand.

      --  Add / remove file name in maxima/src/maxima.system

      --  Verify that
          "sh bootstrap; ./configure --enable-foolisp; make; make install"
          and "run_testsuite();" all succeed

      --  Merge your work onto master and push the changes as in 1.


  4  Adding / removing a file in maxima/share

      --  Copy new file / remove old file
          as you did in 3.

      --  Add / remove file name in maxima/share/Makefile.am

      --  Verify that
          "sh bootstrap; ./configure --enable-foolisp; make; make install"
          and "run_testsuite();" all succeed

      --  Merge your work onto master and push the changes as in 1.


  5.1  Creating a new share package

       E.g., new package name = my_package

      -- Naming conventions:

         write_long_names_like_this, andNotLikeThisPlease,
         norlikethiseitherthanks

         spell_out_names, dnt_try_sv_typng_w_abbrvs_tnx

      -- Create a new directory my_package

      -- Put Lisp and/or Maxima files in the directory

         At least one file must be named my_package.lisp or my_package.mac
         Otherwise load(my_package) fails

      -- Create texinfo documentation file my_package.texi
         (PLEASE CREATE DOCUMENTATION, THANK YOU)

         my_package.texi goes in maxima/doc/info
         (same as other texinfo files)

         Use maxima/share/template.texi as a template for my_package.texi

      -- Create test file rtest_my_package.mac
         (PLEASE CREATE A TEST FILE, THANK YOU)

         Test file contains pairs of expressions:
         input expression, then expected result

         batch("my_package/rtest_my_package.mac", test);
         executes the test


  5.2  Adding a directory in maxima/share
  
      --  Create a scratch/development branch as in 1.

      --  Make the new directory and put the new files in it

      --  Add the all the files in your new directory and commit this change:
          git add .
	  git commit -m 'Message' -a

      --  Put the my_package files on the file list of maxima/share/Makefile.am

      --  Add my_package to SHARE-SUBDIRS-LIST in maxima/src/init-cl.lisp

      --  Move my_package.texi to maxima/doc/info

          Put my_package.texi on the list of files in
          maxima/doc/info/Makefile.am

          Put my_package on the list of topics in maxima/doc/info/maxima.texi
          See instructions in comments at top of maxima/share/template.texi

      --  Verify that
          "sh bootstrap; ./configure --enable-foolisp; make; make install"
          and "run_testsuite();" all succeed

      --  Commit and push your work as in 1.


  6  Adding / removing a file in maxima/tests

      --  Create a scratch/development branch as in 1.

      --  Copy new file / remove old file
          and execute "git add" / "git rm"

      --  Add / remove file name in maxima/tests/Makefile.am

      --  Add / remove file name in maxima/tests/testsuite.lisp

      --  Verify that
          "sh bootstrap; ./configure --enable-foolisp; make; make install"
          and "run_testsuite();" all succeed

      --  Commit and push your work as in 1.


  7  Updating the website

    See the Git module "site-xml", particularly "README" there.


  8.1  Backups of Git

    All you need is the rsync tool and some disk space.

    Issue the following command:

    rsync -av 'rsync://maxima.git.sourceforge.net/gitroot/maxima/*' .


  8.2  Backups of the ML subscribers list

    You need to be a list admin to do that. Other then that you only
    need a mail client to send mailman commands to
    maxima-request@math.utexas.edu

    The command to get the subscribers list is "who" followed by the
    list admin password. Sending an empty mail with "who XXX" in the
    subject line should be enough.

    I have the following cron.weekly script to do this automatically:

    | #! /bin/sh
    | 
    | su myuser -c "echo end | mail -s \"who password\" maxima-request@math.utexas.edu"


  8.3  Other Backups

    Backups of the following stuff would be nice too:

    - wiki

    - bug database