Artifact 39df1905cf6f023756cbdff39af51d26ed6d4554:
- File developer-guide.mkd — part of check-in [da935c7872] at 2019-01-01 15:05:10 on branch trunk — Add developer guide which is used for making releases. (user: stephanie.gawroriski size: 3229)
0000: 23 20 44 65 76 65 6c 6f 70 65 72 20 47 75 69 64 # Developer Guid 0010: 65 0a 0a 54 68 69 73 20 69 73 20 61 20 67 75 69 e..This is a gui 0020: 64 65 20 66 6f 72 20 64 65 76 65 6c 6f 70 65 72 de for developer 0030: 73 20 74 6f 20 66 6f 6c 6c 6f 77 20 66 6f 72 20 s to follow for 0040: 76 61 72 69 6f 75 73 20 70 61 72 74 73 20 6f 66 various parts of 0050: 20 74 68 65 20 72 65 70 6f 73 69 74 6f 72 79 2e the repository. 0060: 0a 0a 23 23 20 52 65 6c 65 61 73 69 6e 67 0a 0a ..## Releasing.. 0070: 57 68 65 6e 20 61 20 72 65 6c 65 61 73 65 20 69 When a release i 0080: 73 20 74 6f 20 62 65 20 6d 61 64 65 2c 20 69 74 s to be made, it 0090: 20 69 73 20 70 65 72 66 6f 72 6d 65 64 20 69 6e is performed in 00a0: 20 61 6e 6f 74 68 65 72 20 62 72 61 6e 63 68 20 another branch 00b0: 61 6e 64 20 62 65 63 6f 6d 65 73 0a 73 65 70 61 and becomes.sepa 00c0: 72 61 74 65 20 66 72 6f 6d 20 60 74 72 75 6e 6b rate from `trunk 00d0: 60 2e 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 `. This means th 00e0: 61 74 20 60 74 72 75 6e 6b 60 20 69 73 20 61 6c at `trunk` is al 00f0: 77 61 79 73 20 69 6e 20 61 20 73 74 61 74 65 20 ways in a state 0100: 6f 66 0a 70 65 72 70 65 74 75 61 6c 20 64 65 76 of.perpetual dev 0110: 65 6c 6f 70 6d 65 6e 74 2e 20 57 69 74 68 69 6e elopment. Within 0120: 20 74 68 65 73 65 20 62 72 61 6e 63 68 65 73 2c these branches, 0130: 20 74 68 65 72 65 20 61 72 65 20 62 75 67 20 66 there are bug f 0140: 69 78 65 73 20 61 6e 64 0a 72 65 6c 65 61 73 65 ixes and.release 0150: 73 2e 20 57 68 65 6e 20 61 20 63 6f 6d 6d 69 74 s. When a commit 0160: 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 61 20 is ready for a 0170: 72 65 6c 65 61 73 65 20 74 68 65 6e 20 69 74 20 release then it 0180: 73 68 6f 75 6c 64 20 6a 75 73 74 20 62 65 20 74 should just be t 0190: 61 67 67 65 64 0a 61 6e 64 20 62 75 69 6c 74 20 agged.and built 01a0: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 20 49 74 20 accordingly. It 01b0: 69 73 20 62 65 73 74 20 74 6f 20 61 76 6f 69 64 is best to avoid 01c0: 20 68 61 76 69 6e 67 20 72 65 6c 65 61 73 65 73 having releases 01d0: 20 61 6e 64 20 73 75 63 68 20 69 6e 20 74 68 65 and such in the 01e0: 0a 60 74 72 75 6e 6b 60 20 62 72 61 6e 63 68 20 .`trunk` branch 01f0: 62 65 63 61 75 73 65 20 69 74 20 77 69 6c 6c 20 because it will 0200: 63 6f 6d 70 6c 69 63 61 74 65 20 62 75 67 20 66 complicate bug f 0210: 69 78 65 73 20 61 6e 64 20 6f 74 68 65 72 20 74 ixes and other t 0220: 68 69 6e 67 73 2e 20 53 6f 0a 77 68 65 6e 20 61 hings. So.when a 0230: 20 72 65 6c 65 61 73 65 20 69 73 20 74 6f 20 62 release is to b 0240: 65 20 6d 61 64 65 3a 0a 0a 20 2a 20 55 70 64 61 e made:.. * Upda 0250: 74 65 20 74 68 65 20 63 68 61 6e 67 65 6c 6f 67 te the changelog 0260: 20 77 69 74 68 20 74 68 65 20 70 6c 61 6e 6e 65 with the planne 0270: 64 20 72 65 6c 65 61 73 65 20 64 61 74 65 20 69 d release date i 0280: 66 20 69 74 20 69 73 20 6b 6e 6f 77 6e 20 61 74 f it is known at 0290: 20 74 68 65 0a 20 20 20 74 69 6d 65 2c 20 6f 74 the. time, ot 02a0: 68 65 72 77 69 73 65 20 69 74 20 69 73 20 6e 6f herwise it is no 02b0: 74 20 6b 6e 6f 77 6e 2e 0a 20 2a 20 46 6f 72 6b t known.. * Fork 02c0: 20 74 68 65 20 62 72 61 6e 63 68 20 61 6e 64 20 the branch and 02d0: 6d 61 6b 65 20 61 20 6e 65 77 20 62 72 61 6e 63 make a new branc 02e0: 68 20 66 72 6f 6d 20 60 74 72 75 6e 6b 60 20 66 h from `trunk` f 02f0: 6f 72 20 74 68 65 20 72 65 6c 65 61 73 65 20 74 or the release t 0300: 6f 0a 20 20 20 62 65 20 64 6f 6e 65 2c 20 61 6e o. be done, an 0310: 20 65 78 61 6d 70 6c 65 20 77 6f 75 6c 64 20 62 example would b 0320: 65 20 60 72 65 6c 65 61 73 65 2d 30 2e 32 2e 78 e `release-0.2.x 0330: 60 2e 0a 20 2a 20 49 6e 20 74 68 65 20 6e 65 77 `.. * In the new 0340: 20 60 72 65 6c 65 61 73 65 2d 30 2e 32 2e 78 60 `release-0.2.x` 0350: 20 62 72 61 6e 63 68 2c 20 75 70 64 61 74 65 20 branch, update 0360: 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 the version numb 0370: 65 72 73 20 69 6e 20 74 68 65 0a 20 20 20 61 70 ers in the. ap 0380: 70 72 6f 70 72 69 61 74 65 20 70 6c 61 63 65 73 propriate places 0390: 20 73 6f 20 74 68 69 6e 67 73 20 61 72 65 20 75 so things are u 03a0: 70 64 61 74 65 64 2e 0a 20 2a 20 54 61 67 20 74 pdated.. * Tag t 03b0: 68 65 20 63 6f 6d 6d 69 74 20 61 73 20 60 30 2e he commit as `0. 03c0: 32 2e 30 60 20 6f 72 20 61 6e 20 69 6e 63 72 65 2.0` or an incre 03d0: 61 73 69 6e 67 20 72 65 6c 65 61 73 65 20 76 65 asing release ve 03e0: 72 73 69 6f 6e 0a 20 20 20 28 65 78 61 6d 70 6c rsion. (exampl 03f0: 65 3a 20 60 30 2e 32 2e 31 60 29 20 66 6f 72 20 e: `0.2.1`) for 0400: 65 61 63 68 20 69 6e 63 72 65 61 73 69 6e 67 20 each increasing 0410: 72 65 6c 65 61 73 65 2e 0a 20 2a 20 44 6f 20 61 release.. * Do a 0420: 6c 6c 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 72 65 ll the common re 0430: 6c 65 61 73 65 20 73 74 75 66 66 2e 0a 20 2a 20 lease stuff.. * 0440: 57 68 69 6c 65 20 69 6e 20 60 74 72 75 6e 6b 60 While in `trunk` 0450: 2c 20 64 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 , do the followi 0460: 6e 67 3a 0a 20 20 20 2a 20 54 68 65 20 64 65 76 ng:. * The dev 0470: 65 6c 6f 70 6d 65 6e 74 20 76 65 72 73 69 6f 6e elopment version 0480: 20 63 61 6e 20 62 65 20 62 75 6d 70 65 64 20 69 can be bumped i 0490: 6e 20 77 68 69 63 68 20 63 61 73 65 0a 20 20 20 n which case. 04a0: 20 20 74 68 65 20 76 65 72 73 69 6f 6e 20 77 69 the version wi 04b0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 ll be incremente 04c0: 64 20 62 79 20 74 77 6f 20 61 6e 64 20 77 69 6c d by two and wil 04d0: 6c 20 62 65 20 6f 64 64 20 28 33 2c 20 35 2c 20 l be odd (3, 5, 04e0: 37 2c 20 65 74 63 2e 29 2e 0a 20 20 20 2a 20 41 7, etc.).. * A 04f0: 64 64 20 74 68 65 20 6e 65 78 74 20 76 65 72 73 dd the next vers 0500: 69 6f 6e 20 74 6f 20 74 68 65 20 63 68 61 6e 67 ion to the chang 0510: 65 6c 6f 67 2c 20 73 6f 20 74 68 61 74 20 69 74 elog, so that it 0520: 20 6d 61 79 20 62 65 20 75 70 64 61 74 65 64 20 may be updated 0530: 77 68 65 6e 0a 20 20 20 20 20 74 68 65 72 65 20 when. there 0540: 69 73 20 61 20 6e 65 77 20 6d 61 6a 6f 72 20 63 is a new major c 0550: 68 61 6e 67 65 2e 0a 0a 23 23 23 20 42 75 67 2d hange...### Bug- 0560: 66 69 78 20 61 6e 64 20 4f 74 68 65 72 77 69 73 fix and Otherwis 0570: 65 20 52 65 6c 65 61 73 65 73 0a 0a 49 66 20 61 e Releases..If a 0580: 20 62 75 67 2d 66 69 78 20 6f 72 20 6f 74 68 65 bug-fix or othe 0590: 72 77 69 73 65 20 68 61 73 20 74 6f 20 62 65 20 rwise has to be 05a0: 64 6f 6e 65 20 6f 6e 20 61 20 72 65 6c 65 61 73 done on a releas 05b0: 65 20 76 65 72 73 69 6f 6e 2c 20 73 69 6e 63 65 e version, since 05c0: 20 74 68 65 0a 72 65 6c 65 61 73 65 20 69 73 20 the.release is 05d0: 69 6e 20 69 74 73 20 6f 77 6e 20 62 72 61 6e 63 in its own branc 05e0: 68 2c 20 74 68 65 20 77 6f 72 6b 20 63 61 6e 20 h, the work can 05f0: 62 65 20 64 6f 6e 65 20 69 6e 20 74 68 61 74 20 be done in that 0600: 62 72 61 6e 63 68 2e 20 41 6e 79 20 66 69 78 65 branch. Any fixe 0610: 73 0a 73 68 6f 75 6c 64 20 68 61 76 65 20 61 6c s.should have al 0620: 72 65 61 64 79 20 62 65 65 6e 20 6d 61 64 65 20 ready been made 0630: 69 6e 20 60 74 72 75 6e 6b 60 20 69 66 20 61 70 in `trunk` if ap 0640: 70 6c 69 63 61 62 6c 65 2c 20 74 68 65 6e 20 69 plicable, then i 0650: 74 20 63 61 6e 20 62 65 0a 63 68 65 72 72 79 20 t can be.cherry 0660: 70 69 63 6b 65 64 20 69 6e 74 6f 20 74 68 65 20 picked into the 0670: 72 65 6c 65 61 73 65 20 62 72 61 6e 63 68 2e 20 release branch. 0680: 54 68 65 6e 20 6f 6e 63 65 20 74 68 65 20 66 69 Then once the fi 0690: 78 65 73 20 68 61 76 65 20 62 65 65 6e 20 6d 61 xes have been ma 06a0: 64 65 20 61 6e 64 0a 61 20 6e 65 77 20 76 65 72 de and.a new ver 06b0: 73 69 6f 6e 20 69 73 20 72 65 6c 65 61 73 65 64 sion is released 06c0: 20 74 68 65 20 72 65 6c 65 61 73 65 20 76 65 72 the release ver 06d0: 73 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 sion should be i 06e0: 6e 63 72 65 6d 65 6e 74 65 64 20 28 74 68 61 74 ncremented (that 06f0: 20 69 73 0a 60 30 2e 32 2e 30 60 20 74 6f 20 60 is.`0.2.0` to ` 0700: 30 2e 32 2e 31 60 20 74 6f 20 60 30 2e 32 2e 32 0.2.1` to `0.2.2 0710: 60 29 2e 20 54 68 65 6e 20 61 6e 79 20 6f 66 20 `). Then any of 0720: 74 68 65 20 72 65 6c 65 61 73 65 20 72 65 6c 61 the release rela 0730: 74 65 64 20 73 74 75 66 66 20 73 68 6f 75 6c 64 ted stuff should 0740: 0a 62 65 20 64 6f 6e 65 2e 0a 0a 23 23 23 20 43 .be done...### C 0750: 6f 6d 6d 6f 6e 20 52 65 6c 65 61 73 65 20 53 74 ommon Release St 0760: 75 66 66 0a 0a 57 68 65 6e 20 61 20 72 65 6c 65 uff..When a rele 0770: 61 73 65 20 69 73 20 64 6f 6e 65 2c 20 61 6c 6c ase is done, all 0780: 20 6f 66 20 74 68 65 20 62 69 6e 61 72 69 65 73 of the binaries 0790: 20 61 6e 64 20 61 63 63 6f 72 64 69 6e 67 20 69 and according i 07a0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 75 73 74 20 nformation must 07b0: 62 65 0a 75 70 64 61 74 65 64 2e 20 49 74 20 69 be.updated. It i 07c0: 73 20 61 73 73 75 6d 65 64 20 74 68 61 74 20 60 s assumed that ` 07d0: 53 51 55 49 52 52 45 4c 4a 4d 45 60 20 69 73 20 SQUIRRELJME` is 07e0: 61 6e 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 76 an environment v 07f0: 61 72 69 61 62 6c 65 20 74 6f 20 74 68 65 0a 72 ariable to the.r 0800: 6f 6f 74 20 6f 66 20 74 68 65 20 53 71 75 69 72 oot of the Squir 0810: 72 65 6c 4a 4d 45 20 73 6f 75 72 63 65 20 74 72 relJME source tr 0820: 65 65 2e 20 43 68 65 63 6b 6f 75 74 20 74 68 65 ee. Checkout the 0830: 20 74 61 67 20 6f 72 20 63 6f 6d 6d 69 74 20 77 tag or commit w 0840: 68 69 63 68 20 74 68 65 0a 72 65 6c 65 61 73 65 hich the.release 0850: 20 69 73 20 74 6f 20 62 65 20 64 6f 6e 65 20 6f is to be done o 0860: 6e 2e 20 54 68 65 6e 20 72 75 6e 20 74 68 65 20 n. Then run the 0870: 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6d 6d 61 6e following comman 0880: 64 3a 0a 0a 20 2a 20 60 24 53 51 55 49 52 52 45 d:.. * `$SQUIRRE 0890: 4c 4a 4d 45 2f 75 74 69 6c 73 2d 64 65 76 2f 75 LJME/utils-dev/u 08a0: 70 6c 6f 61 64 72 65 6c 65 61 73 65 2e 73 68 20 ploadrelease.sh 08b0: 24 5f 5f 72 65 6c 65 61 73 65 5f 76 65 72 73 69 $__release_versi 08c0: 6f 6e 5f 5f 60 0a 0a 54 68 69 73 20 77 69 6c 6c on__`..This will 08d0: 20 70 65 72 66 6f 72 6d 20 61 6e 20 61 75 74 6f perform an auto 08e0: 2d 62 75 69 6c 64 20 6f 66 20 65 76 65 72 79 74 -build of everyt 08f0: 68 69 6e 67 20 61 6e 64 20 74 68 65 6e 20 73 74 hing and then st 0900: 6f 72 65 20 74 68 65 20 72 65 6c 65 61 73 65 20 ore the release 0910: 69 6e 0a 74 68 65 20 60 24 5f 5f 72 65 6c 65 61 in.the `$__relea 0920: 73 65 5f 76 65 72 73 69 6f 6e 5f 5f 60 20 64 69 se_version__` di 0930: 72 65 63 74 6f 72 79 2c 20 74 68 65 73 65 20 62 rectory, these b 0940: 69 6e 61 72 69 65 73 20 61 72 65 20 69 6d 70 6f inaries are impo 0950: 72 74 61 6e 74 2e 20 4f 6e 63 65 20 74 68 65 0a rtant. Once the. 0960: 62 69 6e 61 72 69 65 73 20 61 6e 64 20 73 6f 75 binaries and sou 0970: 72 63 65 73 20 61 72 65 20 62 75 69 6c 74 2c 20 rces are built, 0980: 74 68 65 79 20 73 68 6f 75 6c 64 20 62 65 20 75 they should be u 0990: 70 6c 6f 61 64 65 64 20 74 6f 20 74 68 65 20 66 ploaded to the f 09a0: 6f 6c 6c 6f 77 69 6e 67 0a 6c 6f 63 61 74 69 6f ollowing.locatio 09b0: 6e 73 3a 0a 0a 20 2a 20 46 6f 73 73 69 6c 20 28 ns:.. * Fossil ( 09c0: 3c 68 74 74 70 73 3a 2f 2f 6d 75 6c 74 69 70 68 <https://multiph 09d0: 61 73 69 63 61 70 70 73 2e 6e 65 74 2f 3e 29 0a asicapps.net/>). 09e0: 20 20 20 2a 20 54 68 65 20 60 75 70 6c 6f 61 64 * The `upload 09f0: 72 65 6c 65 61 73 65 2e 73 68 60 20 73 63 72 69 release.sh` scri 0a00: 70 74 20 74 61 6b 65 73 20 63 61 72 65 20 6f 66 pt takes care of 0a10: 20 70 75 74 74 69 6e 67 20 74 68 65 20 66 69 6c putting the fil 0a20: 65 73 20 69 6e 20 74 68 65 0a 20 20 20 20 20 72 es in the. r 0a30: 65 70 6f 73 69 74 6f 72 79 2e 0a 20 20 20 2a 20 epository.. * 0a40: 59 6f 75 20 77 69 6c 6c 20 6e 65 65 64 20 74 6f You will need to 0a50: 20 65 64 69 74 20 74 68 65 20 64 6f 77 6e 6c 6f edit the downlo 0a60: 61 64 20 70 61 67 65 20 74 6f 20 61 64 64 20 74 ad page to add t 0a70: 68 65 20 6e 65 77 20 76 65 72 73 69 6f 6e 2c 20 he new version, 0a80: 74 68 69 73 0a 20 20 20 20 20 77 69 6c 6c 20 62 this. will b 0a90: 65 20 64 6f 6e 65 20 77 69 74 68 20 60 66 6f 73 e done with `fos 0aa0: 73 69 6c 20 75 6e 76 65 72 73 69 6f 6e 20 65 64 sil unversion ed 0ab0: 69 74 20 64 6f 77 6e 6c 6f 61 64 2e 6d 6b 64 60 it download.mkd` 0ac0: 2e 0a 20 20 20 2a 20 53 79 6e 63 68 72 6f 6e 69 .. * Synchroni 0ad0: 7a 65 20 74 68 65 20 72 65 70 6f 73 69 74 6f 72 ze the repositor 0ae0: 79 20 77 69 74 68 20 74 68 65 20 75 6e 76 65 72 y with the unver 0af0: 73 69 6f 6e 65 64 20 73 70 61 63 65 2e 0a 20 2a sioned space.. * 0b00: 20 47 69 74 48 75 62 0a 20 20 20 2a 20 47 6f 20 GitHub. * Go 0b10: 74 6f 20 72 65 6c 65 61 73 65 73 2e 0a 20 20 20 to releases.. 0b20: 2a 20 44 72 61 66 74 20 61 20 6e 65 77 20 72 65 * Draft a new re 0b30: 6c 65 61 73 65 2e 0a 20 20 20 2a 20 43 68 6f 6f lease.. * Choo 0b40: 73 65 20 74 68 65 20 72 65 6c 65 61 73 65 20 74 se the release t 0b50: 61 67 20 79 6f 75 20 6a 75 73 74 20 6d 61 64 65 ag you just made 0b60: 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 72 . Note that ther 0b70: 65 20 6d 69 67 68 74 20 62 65 20 61 20 64 65 6c e might be a del 0b80: 61 79 0a 20 20 20 20 20 62 65 66 6f 72 65 20 47 ay. before G 0b90: 69 74 48 75 62 20 69 73 20 75 70 64 61 74 65 64 itHub is updated 0ba0: 2c 20 73 6f 20 62 65 20 70 61 74 69 65 6e 74 20 , so be patient 0bb0: 6f 72 20 66 6f 72 63 65 20 69 74 20 74 6f 20 75 or force it to u 0bc0: 70 64 61 74 65 20 6d 61 6e 75 61 6c 6c 79 2e 0a pdate manually.. 0bd0: 20 20 20 2a 20 54 69 74 6c 65 20 74 68 65 20 72 * Title the r 0be0: 65 6c 65 61 73 65 2e 0a 20 2a 20 53 6f 75 72 63 elease.. * Sourc 0bf0: 65 46 6f 72 67 65 0a 20 20 20 2a 20 43 72 65 61 eForge. * Crea 0c00: 74 65 20 61 20 6e 65 77 20 64 69 72 65 63 74 6f te a new directo 0c10: 72 79 20 66 6f 72 20 74 68 65 20 72 65 6c 65 61 ry for the relea 0c20: 73 65 20 6e 75 6d 62 65 72 2e 0a 20 20 20 2a 20 se number.. * 0c30: 55 70 6c 6f 61 64 20 61 6c 6c 20 6f 66 20 74 68 Upload all of th 0c40: 65 20 66 69 6c 65 73 20 69 6e 74 6f 20 74 68 61 e files into tha 0c50: 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 20 20 20 t directory.. 0c60: 2a 20 41 70 70 72 6f 70 72 69 61 74 65 6c 79 20 * Appropriately 0c70: 73 65 74 20 74 68 65 20 6f 70 65 72 61 74 69 6e set the operatin 0c80: 67 20 73 79 73 74 65 6d 73 20 66 6f 72 20 74 68 g systems for th 0c90: 65 20 62 69 6e 61 72 69 65 73 2e 0a 0a e binaries...