developer-guide.mkd

   1 # Developer Guide
   2
   3 This is a guide for developers to follow for various parts of the repository.
   4 This is mostly intended for maintainers of _SquirrelJME_.
   5
   6  * See the [Building](building.mkd).
   7  * Also see [Contributing](contributing.mkd).
   8
   9 ## Accepting Changes
  10
  11 ***TO BE WRITTEN***
  12
  13 ### Loading Contributions
  14
  15 ***TO BE WRITTEN***
  16
  17 #### Via Fossil Bundles
  18
  19 ***TO BE WRITTEN***
  20
  21 #### Via Git Bundles
  22
  23 ***TO BE WRITTEN***
  24
  25  * `git am < my-branch.bun`
  26
  27 ### Merging Branches
  28
  29 To merge a branch locally, do the following:
  30
  31  * Update to the branch that will get submissions merged into:
  32    * `fossil update trunk`
  33  * Merge the other branch into your current `trunk`:
  34    * `fossil merge other-branch`
  35  * Commit the changes:
  36    * `fossil commit`
  37    * Be sure to have a meaningful commit message, if the code is from a
  38      merge request on a remote repository, have the following in the commit
  39      message:
  40      * GitHub: `(GitHub Closes #1234)`
  41      * GitLab: `(GitLab Closes !1234)`
  42  * Synchronize the repositories:
  43    * `fossil sync -u`
  44
  45 ## Releasing
  46
  47 When a release is to be made, it is performed in another branch and becomes
  48 separate from `trunk`. This means that `trunk` is always in a state of
  49 perpetual development. Within these branches, there are bug fixes and
  50 releases. When a commit is ready for a release then it should just be tagged
  51 and built accordingly. It is best to avoid having releases and such in the
  52 `trunk` branch because it will complicate bug fixes and other things. So
  53 when a release is to be made:
  54
  55  * Update the changelog with the planned release date if it is known at the
  56    time, otherwise it is not known.
  57  * Fork the branch and make a new branch from `trunk` for the release to
  58    be done, an example would be `release-0.2.x`.
  59  * In the new `release-0.2.x` branch, update the version numbers in the
  60    appropriate places so things are updated.
  61  * Tag the commit as `0.2.0` or an increasing release version
  62    (example: `0.2.1`) for each increasing release.
  63  * Do all the common release stuff.
  64  * While in `trunk`, do the following:
  65    * The development version can be bumped in which case
  66      the version will be incremented by two and will be odd (3, 5, 7, etc.).
  67    * Add the next version to the changelog, so that it may be updated when
  68      there is a new major change.
  69
  70 ### RetroArch
  71
  72 For RetroArch, the SquirrelJME recipes should be updated to reflect the
  73 release tag.
  74
  75  * <https://github.com/libretro/libretro-super>
  76
  77 ### Bug-fix and Otherwise Releases
  78
  79 If a bug-fix or otherwise has to be done on a release version, since the
  80 release is in its own branch, the work can be done in that branch. Any fixes
  81 should have already been made in `trunk` if applicable, then it can be
  82 cherry picked into the release branch. Then once the fixes have been made and
  83 a new version is released the release version should be incremented (that is
  84 `0.2.0` to `0.2.1` to `0.2.2`). Then any of the release related stuff should
  85 be done.
  86
  87 ### Common Release Stuff
  88
  89 ***THIS IS OUT OF DATE AND WILL BE CHANGED TO BE DONE PURELY BY CI/CD,***
  90 ***SO THAT IT IS AUTOMATICALLY DONE AND CHECKED WITHOUT ISSUE.***
  91
  92 When a release is done, all of the binaries and according information must be
  93 updated. It is assumed that `SQUIRRELJME` is an environment variable to the
  94 root of the SquirrelJME source tree. Checkout the tag or commit which the
  95 release is to be done on. Then run the following command:
  96
  97  * `$SQUIRRELJME/utils-dev/uploadrelease.sh $__release_version__`
  98
  99 This will perform an auto-build of everything and then store the release in
 100 the `$__release_version__` directory, these binaries are important. Once the
 101 binaries and sources are built, they should be uploaded to the following
 102 locations:
 103
 104  * Fossil (<https://multiphasicapps.net/>)
 105    * The `uploadrelease.sh` script takes care of putting the files in the
 106      repository.
 107    * You will need to edit the download page to add the new version, this
 108      will be done with `fossil unversion edit download.mkd`.
 109    * Synchronize the repository with the unversioned space.
 110  * GitHub
 111    * Go to releases.
 112    * Draft a new release.
 113    * Choose the release tag you just made. Note that there might be a delay
 114      before GitHub is updated, so be patient or force it to update manually.
 115    * Title the release.
 116  * SourceForge
 117    * Create a new directory for the release number.
 118    * Upload all of the files into that directory.
 119    * Appropriately set the operating systems for the binaries.
 120
 121 ## Importing SquirrelJME Into Another Project
 122
 123 Any one of SquirrelJME's modules can be used as a dependency for a project.
 124 Note that the versions that are used depend on if a release is being used or
 125 not, which is in the format of `M.m.r` for releases and `M.m.r-SNAPSHOT` for
 126 development versions. Note that even minor versions are releases (ex: `0.4.0`),
 127 and odd minor versions are development versions (ex: `0.3.0-SNAPSHOT`).
 128
 129 ### Snapshot Repository
 130
 131 ```xml
 132 <!-- Maven -->
 133 <project>
 134     <repositories>
 135         <repository>
 136             <id>oss.sonatype.org-snapshot</id>
 137             <url>https://oss.sonatype.org/content/repositories/snapshots</url>
 138             <releases>
 139                 <enabled>false</enabled>
 140             </releases>
 141             <snapshots>
 142                 <enabled>true</enabled>
 143             </snapshots>
 144         </repository>
 145     </repositories>
 146 </project>
 147 ```
 148
 149 ```groovy
 150 // Gradle
 151 repositories {
 152     maven {
 153         url "https://oss.sonatype.org/content/repositories/snapshots"
 154     }
 155 }
 156 ```
 157
 158 # Debugging
 159
 160 SquirrelJME's VMs may be debugged by having it connect to a debugger or
 161 waiting for a debug connection. Debugging happens purely over TCP/IP. It
 162 is not possible to use existing debuggers to debug SquirrelJME virtual machines
 163 there are debug interfaces available through standardized JDWP. Note that
 164 it is _not_ recommended for the debugger port to be open to the internet as
 165 it will allow the remote debugger to have access to all the virtual machine
 166 internals.
 167
 168 Arguments to the virtual machines for _SpringCoat_, _SummerCoat_, etc.:
 169
 170  * Connect to remote debugger
 171    * `-Dsquirreljme.jdwp=localhost:5005`
 172  * Listen for a remote connection
 173    * `-Dsquirreljme.jdwp=:5005`
 174
 175 Instructions for specific debuggers:
 176
 177  * [jdb](
 178    https://docs.oracle.com/javase/7/docs/technotes/tools/solaris/jdb.html)
 179    * Connect:
 180      * `jdb -connect com.sun.jdi.SocketAttach:hostname=localhost,port=5005`
 181    * Listen:
 182      * `jdb -connect com.sun.jdi.SocketListen:port=5005`
 183  * [IntelliJ](
 184    https://www.jetbrains.com/help/idea/attaching-to-local-process.html)
 185  * [Eclipse](
 186    https://www.eclipse.org/community/eclipse_newsletter/2017/june/article1.php)