Skip to content

Keyman Project Scopes

Jump to bottom
Marc Durdin edited this page Feb 21, 2024 · 4 revisions

The Keyman Project: Scopes

The Keyman project is quite large. At last count, there were over 1800 different project files covering a wide variety of programming languages and platforms. This needs careful management! We try and use names carefully in a number of places to group files logically.

We have defined a nested set of project scopes. At the top level, we use platform targets (e.g. android, windows), developer, and a couple of umbrella categories (common, oem). Within each of these scopes, we have further broken down into sub scopes that attempt to bucket the logical layout of the projects within the parent scope.

Not everything gets a scope. Once we get down a couple of layers, we start to use project-level namespacing. These project-level namespaces should inherit from the parent scope, but are currently inconsistent. See Project-level scopes for more detail.

Scopes appear in various places:

  • paths, e.g.:
    • /windows/
    • /android/
  • commit messages + PRs:
    • fix(windows):
    • feat(android):
    • chore(common/resources):
  • GitHub labels:
    • windows/
    • android/
    • common/models/
  • NPM / Lerna package names
    • @keymanapp/web-utils

TODO: At present, paths are not especially consistently related to scopes. Over time, we'll try and clean these up.

TODO: project-level namespaces are very inconsistent.

Scope Usage

A number of our tools and processes refer to scopes. This is a non-exhaustive list:

  • resources/scopes/scopes.json
    • This is the master list of scopes. All other code should reference this, for example resources/git-hooks/commit-msg
  • resources/shellHelperFunctions.sh
    • TODO: update to use scopes.json
  • resources/build/trigger-definitions.inc.sh [as paths]
    • TODO: update to merge with scopes.json?
    • Usage in these three above could be merged to resources/scopes/scopes.json in the future
  • history management
    • TODO: use scopes.json
  • GitHub labels
    • When labelling PRs and Issues, Include all layers of scoping -- common/ and common/models/ and common/models/types/ -- so that we can easily filter.
  • status.keyman.com
    • With reference to GitHub labels
  • NPM modules
  • Web compilation, Web + UI module, dev-resource communication

Management of Scopes

Not everything needs a subscope. Let's not go overboard. Reasons to create a new scope:

  • It's a module or library shared among multiple projects
  • The naming rules for the code implies scoping, for example Node.js modules. Note that not every Node.js module needs its own scope.
  • Starting to get many files that need to be logically grouped together and perhaps managed by a single person.
  • All of these may just be namespaces rather than a scope. Err on the side of namespaces!

Some rules:

  • Lower case a-z only: no punctuation or digits
  • Shorter and clearer wins (e.g. models, not lm, not lmlayer, not lexicalmodellayer)
  • Sub scopes should have names that match other sub scopes if possible, e.g. engine appears in most platform-level scopes.
  • Top-level scopes are reserved for platform designators, developer, common, and resources. These correspond roughly to the target projects and match the areas on status.keyman.com.

Where possible, we use / (forward slash) as a scope separator. If that is not possible, use - (hyphen), or at a pinch _ (underscore). For example:

  • keyman/android/app
  • keyman-android-app
  • keyman_android_app (if forced to!)
  • Node scope formatting: @keymanapp/android-app

Special Cases

For Node modules, we elide or rename some of the scope names to make them less unwieldy:

  • common/core/web → web
    • For example, @keymanapp/web-utils
  • web → keyman

We do not define a scope for “tests” since they're everywhere.

Current Scope Tree

This is the master list of scopes. It should match /resources/scopes/scopes.json.

android
	app
	browser
	engine
	resources
	samples
	
ios
	app
	browser
	engine
	resources
	samples
	
linux
	config
	engine
	resources
	samples

web
	bookmarklet
	engine
	resources
	ui
	samples

mac
	config
	engine
	resources
	samples

windows
	config
	engine
	resources
	samples

developer
	compilers
	ide
	resources (internal to project)
	tools (deployed to users)
	
core

common
	models
		types			@keymanapp/models-types
		templates		@keymanapp/models-templates
		wordbreakers		@keymanapp/models-wordbreakers

	resources
		* may include things like shared testing resources (keyboards) used by tests across various platforms
	ci

oem
	fv
		android
		ios
		windows

Project-level scopes

Projects should have namespaces defined according to the scope tree above. The particulars may vary according to the programming language in use but the names should match.

TODO: This currently lists the project-level scopes in use rather than as they should be. TODO: Complete scope extraction for other platforms

Java (Android): com.keyman.android. ?

Delphi (Windows/Developer):

Current namespace Proposed namespace
Keyman.Configuration
Keyman.Configuration.System
Keyman.Configuration.System.HttpServer
Keyman.Configuration.System.HttpServer.App
Keyman.Configuration.UI
Keyman.Console
Keyman.Developer.System
Keyman.Developer.System.HttpServer
Keyman.Developer.System.Project
Keyman.Developer.UI
Keyman.Developer.UI.Import
Keyman.Developer.UI.Project
Keyman.System
Keyman.System.HttpServer
Keyman.System.Install
Keyman.System.SentryTool
Keyman.System.Standards
Keyman.System.Test
Keyman.System.Util
Keyman.Test
Keyman.Test.Console
Keyman.Test.System
Keyman.Test.System.SentryTool
Keyman.UI
Keyman.Winapi

Notes on Delphi scopes:

  • console. a meta-scope that allows console interaction
  • ui. a meta-scope that allows UI interaction
  • system. a meta-scope that prohibits UI or console interaction

Windows (C++): ?

iOS: Swift doesn’t do namespaces.

macOS: ?

Linux: ?

Web:

  • com.keyman.?

    • .dom, .dom.targets, .dom.utils (for browser-focused code)
    • .keyboards
      • Currently split between keyboard-processor (keyboard definitions) and Web (resource management).
        • As a low priority, I’ve noted that keyboard-processor’s .keyboards classes could serve as their own package… a “keyboard-types” to mirror "lexical-model-types."
    • .osk (OSK-related)
    • .text, .text.prediction (for text processing)
      • .text: keyboard-processor and input-processor
      • .text.prediction: input-processor and lexical-model-layer
    • .utils
      • Common utility code. After #3130 and #3132 (both in review), specified entirely within web-utils.

    Of course, these (for Web) may be (mostly) going the way of the dodo (i.e, extinct, like IE) in the near future.

Other places we use scopes

We should be seeking to use consistent scoping for other locations as well. For example, on help.keyman.com MD recently introduced some namespacing to PHP.

com\keyman com\keyman\help com\keymanweb dev\keyman -> keyman.dev -> developer.keyman.com blog\keyman -> keyman.blog -> blog.keyman.com com\keyman\api com\keyman\downloads com\keyman\status io\github\keyman

Legacy Scopes

This list here comes from the https://github.com/keymanapp/keyman/wiki/Pull-Request-and-Commit-workflow-notes and is out of date. It is included for reference until we finish sorting scopes.

A scope may include a sub-scope; if the work does not belong in a sub-scope, use the parent scope. Scopes correspond roughly to folder names.

  • android -- Keyman for Android
    • android/app -- KMAPro project, including configuration
    • android/browser -- Web browser in KMAPro project
    • android/engine -- KMEA project, including system keyboard extension
    • android/oem -- Android projects in oem folder
  • ci -- Continuous Integration; use a platform scope in preference to this scope if possible
  • common -- use this for resources and common folders and other common code
    • common/core -- Keyman Core project
    • common/lmlayer -- Predictive Text components (note GitHub label is currently web-lm-layer)
  • developer -- Keyman Developer (including Windows and JS components)
    • developer/compiler -- Compilers (command line and within IDE)
    • developer/ide -- Any IDE-related work
    • developer/tools -- Other tools (e.g. kmdecomp, kmconvert)
  • ios -- Keyman for iPhone and iPad
    • ios/app -- Keyman project
    • ios/browser -- Web browser within Keyman project
    • ios/engine -- KeymanEngine project
    • ios/oem -- iOS projects in oem folder
  • linux -- Keyman for Linux
    • linux/config -- Configuration scripts
    • linux/engine -- Keyman Engine
    • linux/ibus -- Ibus Integration
    • linux/oem -- Linux projects in oem folder
  • mac -- Keyman for macOS
    • mac/config -- Configuration utility
    • mac/engine -- Keyman Engine for macOS
    • mac/oem -- macOS projects in oem folder
  • web -- KeymanWeb
    • web/engine -- KeymanWeb Engine; components common to web, android and ios
    • web/oem -- web projects in oem folder
    • web/ui -- KeymanWeb UI components
  • windows -- Keyman Desktop
    • windows/config -- Keyman Configuration
    • windows/engine -- keyman, keyman32, keyman64, keymanx64, kmcomapi, tsysinfo and other Engine projects
    • windows/oem -- Windows projects in oem folder
Clone this wiki locally