doc/README.developer

Purpose of this document
------------------------
This document is the starting point for developers that want to familiarize
themselves with the Little Go project, i.e. developers that are new to the
project, and also me, after I come back to the project after several months
or years :-)


Quick-start guide on how to build and run Little Go
---------------------------------------------------
The current build should work out of the box for Intel Macs, Xcode 15.1 and
the iOS base SDK 17.2 (read NOTES.Build if you need help setting up this
combination). If you want to build with a different setup (especially a Silicon
Mac or an older Xcode version) you will probably encounter errors. Consult
NOTES.build and NOTES.Build.3rdparty, but mostly you will be on your own.

Before you begin, make sure that you have CocoaPods installed on your machine.
Visit the CocoaPods website (https://cocoapods.org/) for instructions how to do
this. Also note that if you want to create a build that runs on an actual iOS
device there are additional requirements. See the section "Device builds" in
NOTES.build.

1. Log in as the user you are going to develop with.
2. Clone the Git repository. Note that downloading just the latest release
   snapshot of the source code is not sufficient because the 3rdparty software
   build depends on Git submodules.
3. Launch Terminal.app and execute these commands:
     cd /path/to/littlego
     git submodule update --init --recursive
     ./script/build-3rdparty-software.sh
4. Wait until the script has built all 3rdparty software packages (see the file
   "NOTES.build.3rdparty" for more details), then execute this command:
     pod install
5. Launch Xcode by opening "Little Go.xcworkspace"
6. Select the "Little Go Debug" scheme, and one of the iPhone or iPad simulator
   destinations, from the toolbar's scheme selector
7. From the menu select Product > Run. The app should now be built in Debug
   mode and launched inside the simulator.


Folder structure
----------------
<root>
 +-- AUTHORS             Principal authors and contributors of the project
 +-- CONTRIBUTING.md     The project's contributing guidelines.
 +-- LICENSE             The Apache license file.
 +-- LICENSE.html        The Apache license in HTML format (for display on the
 |                       device).
 +-- NOTICE              Attribution notices.
 +-- Podfile             The CocoaPods configuration file.
 +-- README.md           Introduction to the project. This file is formatted in
 |                       Markdown and rendered as the front page on GitHub.
 +-- GoogleService-Info.plist   This file is required for using the Crashlytics
 |                              crash reporting service. The file is not under
 |                       version control, you must create and populate it
 |                       yourself with information from your own Firebase
 |                       account. See section "Crash reporting" in
 |                       NOTES.Diagnostics.
 +-- 3rdparty            After cloning the Little Go repository, this folder
 |                       contains some of the 3rdparty software sources as Git
 |                       submodules. After the 3rdparty software build, the
 |                       folder also contains the build results.
 +-- doc                 This folder contains documents not relevant for
 |                       building the Little Go binary; some of these files are
 |                       included in the application bundle that is distributed
 |                       on the App Store.
 +-- doxygen             This folder contains a configuration file Doxyfile for
 |                       Doxygen; the folder is intended to receive the files
 |                       generated by Doxygen.
 +-- resource            This folder contains the project's resources such as
 |                       image files for icons.
 +-- script              This folder contains command line scripts.
 +-- sgf                 This folder contains .sgf files that are used for
 |                       manual testing, demonstrating app features and creating
 |                       marketing material. See the README file in the folder.
 +-- src                 This folder contains the project's source code.
 +-- test                This folder contains the project's unit test files.
 +-- uitest              This folder contains the project's UI test files.


Document reference
------------------
Documents described here are located in the "doc" folder.

ReleaseSteps
  This document lists the steps needed to make a project release.

ChangeLog
  This document contains an annotated compilation of all bugfixes, newly
  implemented features, and other improvements and changes for all released
  versions of the project. The file is parsed and displayed in game under the
  "Changelog" tab. For this to work, the content of this file must follow
  certain guidelines that are documented in DocumentGenerator.h.

NOTES.Build
NOTES.Build.3rdparty
  These documents have detailed notes about the third-party software build
  process, and the project's own build process (including documentation about
  any compiler warnings that currently exist).

NOTES.Architecture
NOTES.Design
littlego.asta
*.jpg
  These documents contain some thoughts that went into architecture and design
  of the project. There are also a few UML diagrams floating around as .jpg
  files. The origin of these diagrams is the Astah project file littlego.asta.
  To open that file you need to install the UML tool Astah - a free community
  edition is available for download here: https://astah.net/

NOTES.Diagnostics
  This document contains instructions what to do with the diagnostics
  information file that is attached to bug report emails. It also contains
  notes in regard to the Crashlytics crash reporting service.

NOTES.SgfSupport
  This document has notes about the project's support for the SGF file format.

BUGS
  This document contains notes about all known irregularities that are
  currently in the project: Compiler warnings, Xcode analyze issues, runtime
  messages printed to the Xcode debug console, unfixed crash reports, etc..
  This document complements the issue list on the project's bug tracker.

TESTING
  This document has information about how the project's automated testing
  facilities work. It also contains a script for manual testing of most of the
  application's features. The intent is to execute the script before a new
  version is released to the App Store.


Other files
-----------
Little Go.xcworkspace
  The Xcode workspace bundle. Open this, not the .xcodeproj bundle.

resource/plist/Info.plist
  The information property list file that describes the Little Go application
  bundle. Certain aspects of the Info.plist file are covered in more detail
  in the document NOTES.Info-plist

script/build-3rdparty-software.sh
  Helper script for downloading and building all 3rdparty software packages that
  are required to build and run Little Go. See NOTES.Build.3rdparty for
  details.


Version control
---------------
The version control system used to maintain this project is Git. The canonical
repository currently resides on GitHub:
- URL for cloning: git://github.com/herzbube/littlego.git
- URL for browsing: https://github.com/herzbube/littlego

The branching model adopted by the project is described in this article:
https://nvie.com/posts/a-successful-git-branching-model/.


Bugtracking
-----------
The bugtracker for the Little Go project is located on GitHub [1]. If you want
to submit a new issue you must be a registered GitHub user (it's free and they
won't bother you with spam!).

Before version 0.9.1, all issues were tracked on a private bugtracker [2]. If
you are really desperate about the project's history :-) you can browse the few
but closed bugs that are still floating around there.

[1] https://github.com/herzbube/littlego/issues
[2] https://bugs.herzbube.ch/


User manual
-----------
The application's user manual is maintained as a separate project on GitHub [1]
to avoid bloat of the source code repository due to large image files that can
potentially change with every new release of the app.

[1] https://github.com/herzbube/littlego-usermanual


Source code documentation with Doxygen
--------------------------------------
There is a "doxygen" target that can be used to transform the source code
documentation into a set of HTML files. The target uses a shell script that
assumes that Doxygen is installed in

  /usr/local/bin

This is the standard path for the Homebrew project. If you have doxygen
installed somewhere else (e.g. /sw/bin, /opt/local/bin) you need to change the
target's shell script.

The Doxygen configuration file is located in

  doxygen/Doxyfile

Notes about the configuration:
- Doxygen recursively searches for *.h, *.m and *.mm files in the project
  top-level folder "src".
- Private methods declared in class extensions or categories in the .m files
  are not included in the documentation process. Change this by setting
  EXTRACT_LOCAL_METHODS = YES inside Doxyfile.
- Doxyfile is configured to look for the command line tool "dot" in
    /usr/local/bin
  dot is part of the Graphviz package and is used to generate a couple of
  diagram types (e.g. class diagrams, collaboration diagrams).


On collaboration
----------------
Contributions in any form (coding, UI design, testing, bug reports, creating an
app video preview, website design) are, of course, very welcome!

Code contributors must have a certain level of experience with object-oriented
coding because I don't have enough spare time to offer a lot of training. I will
certainly coach and assist with getting the project to build and run, but a
certain tech-savyness as well as the will to learn Objective-C (the language
that this project is written in) is required.