Skip to content

Latest commit

 

History

History
102 lines (74 loc) · 5.07 KB

CONTRIBUTING.md

File metadata and controls

102 lines (74 loc) · 5.07 KB
Raw

Contributing To The Effort

Contributions welcome! Preliminaries:

Sub-Projects

Desk Accessories

These are pretty easy to write. See the bug tracker (links below) for examples, but anything is welcome. Look at existing DA code for examples, and see the API and MGTK docs for more details.

Disassembly

Pure disassembly changes take place in the disasm branch, which builds identically to the original. The main branch is based on disasm. (NOTE: As time has gone on, much of the disassembly has been done in main and should be 'upstreamed', time permitting.)

Disassembly efforts include:

  1. DeskTop itself
    • The core bits of DeskTop
    • The various overlays
    • The DiskCopy overlay (basically a stand-alone app)
  2. Selector
  3. DeskTop.system launcher

The bulk of the disassembly is complete, with only some procedures that have not been fully analyzed and commented.

Bug Fixes & Enhancements

Issues marked Good First Bug might be good starter projects to learn about the code. New Desk Accessories in particular should be easy to start with.

Localization

MouseDesk originally shipped in French, English, German, Italian. The project has been structured to allow localization into additional languages. Since then, support for Spanish, Portuguese, Swedish and Danish have been added. The work involved for most contributions is just to add an additional column to a spreadsheet which translations for each string.

DeskTop Localization Spreadsheet

If you want to contribute a localization, please contact a project maintainer.

DeskTop Disassembly Burn-Down

To feel confident about making additions and fixes to DeskTop, we need to make sure we're not breaking things. That can be done in some cases by relying on API boundaries, such as between MGTK and the DeskTop application. But DeskTop itself is a big, monolithic application with multiple overlays, so we need to understand nearly all of it before we can start moving code around. (Fortunately, that's mostly behind us now.)

The bin/stats.pl tool provides is a quick and dirty analysis of the progress in turning raw da65 output into something we can confidently modify. Here's a snapshot of the output for some files that could use attention:


desktop/auxmem.s               unscoped:  0  scoped: 46  raw:  0
desktop/main.s                 unscoped:  0  scoped: 28  raw: 12
desktop/ovl_selector_pick.s    unscoped: 15  scoped:  1  raw:  0
disk_copy/auxlc.s              unscoped: 66  scoped: 28  raw:  7
lib/formatdiskii.s             unscoped: 43  scoped: 15  raw:  0
mgtk/mgtk.s                    unscoped:  0  scoped: 10  raw:  8
selector/app.s                 unscoped:  1  scoped: 32  raw:  1
selector/ovl_file_copy.s       unscoped: 42  scoped: 37  raw:  0

  • unscoped counts the number of auto-generated labels like L1234 produced by da65 which are not in two nested scopes. A scope is used for the overall structure of a module, and a nested scope is used for procedures. This counts labels which are not in either, and thus may have some affinity for a particular address and therefore can't be safely moved.

  • scoped counts the number of auto-generated labels like L1234 produced by da65 which are inside two nested scopes. Once a label is local to a procedure it is generally safe to move, although actually understanding the purpose and giving it a more meaningful label is even better.

  • raw counts the number of 16-bit addresses ($1234) in the code; these usually refer to routines, resources, or occasionally buffer locations that need to be understood and replaced with labels.