Airspace Encounter Models Team

MIT Lincoln Laboratory, Homeland Protection and Air Traffic Control Division

Issue Tracking

We encourage the use of the GitHub Issues for bug report, new feature requests, etc. To streamline reporting, refer to the Projects for this organization.

Due to the encounter models routine use in aviation research, we like to minimize the risk of inadvertent bugs or software challenges to maintain the encounter models as a trusted benchmark. To encourage traceability, development should occur via forking.

Workflow

A variety of organizations from academia, federal agencies, federal funded research and development centers (FFRDC), and industry have supported encounter model development. Each organization has different policies on release review and procedures to disseminate content. Organizations may also have their own enterprise self-hosted version control systems.

We recommend the following workflow that perseveres content part of the airspace-encounter-models organization as a “gold benchmark” while promoting a traceable workflow for contributors.

Workflow

We’ll use an illustrative example with MIT Lincoln Laboratory, a FFRDC with strict release review policies, with their public mit-ll organization and a private enterprise system to explain this workflow. For organizations that permit public development, ignore steps with the enterprise instance.

  1. The repository required for development is identified in airspace-encounter-models
  2. This repository is forked by the mit-ll organization.
  3. The new repository on mit-ll organization is cloned by the enterprise self-hosted GitHub. Note you can’t fork from public to private, see this Stack Overflow question for mitigations: Is it possible to fork a public GitHub repo into an enterprise repository?
    • Prior to any changes, there are now three instances of the repository: a private enterprise clone (airspace-encounter-models-internal), a public fork (mit-ll), and the original (airspace-encounter-models).
  4. Development is conducted using branches on the enterprise clone.
  5. When development is over, the clone will be released review according to internal policies.
  6. Once the clone is approved for public release, changes will be pushed to the public fork.
  7. A pull request will be opened to contribute back to the original.
  8. The encounter model administrators will review the pull request and either accept or reject it.

Bugs

According to Wikipedia, a software bug is a:

A software bug is an error, flaw, failure or fault in a computer program or system that causes it to produce an incorrect or unexpected result, or to behave in unintended ways.

Reporting Bugs

  • Ensure the bug was not already reported by searching on GitHub under Issues.
  • If you’re unable to find an open issue addressing the problem, open a new one using the bug report template. Be sure to include a title, a clear description, and as much relevant information as possible.
  • Confirm that the bug report template assigned a BUG label to the issue.

Patching Bugs

  • Open a new GitHub pull request with the patch.
  • Ensure the pull request description clearly describes the problem and solution. Include the relevant issue number if applicable.
  • Before submitting, please read the convention guide to know more about coding conventions and recommended units.

Cosmetic Patch

Changes that are cosmetic in nature, such as fixing whitespaces characters or formatting code, and do not add anything substantial to the stability, functionality, or testability will generally not be accepted. Our rational aligns with those expressed by the Ruby on Rails team.

Enhancements and New Features

According to Wikipedia and IEEE 829, a software feature is a:

A distinguishing characteristic of a software item (e.g., performance, portability, or functionality.

Requesting features

  • Ensure the feature was not already requested by searching on GitHub under Issues.
  • If you’re unable to find an open issue for the desired feature, open a new one using the feature request template. Be sure to include a title, a clear description, and as much relevant information as possible.
  • Confirm that the feature request template assigned an ENHANCEMENT label to the issue.

Developing features

  • Fork the repository associated with the feature request and develop the desired capabilities
  • Open a new GitHub pull request with the enhancement
  • Ensure the pull request description clearly addresses the feature request. Include the relevant issue number. Unlike bugs, enhancements without a traceable issue number will not have the pull request accepted.
  • Before submitting, please read the convention guide to know more about coding conventions and recommended units. Some documentation and code commenting is required for the pull request to be accepted too.

Requesting documentation

Requesting more or a clarification of documentation is a valid feature request. Note as a community development project, it would be nearly impossible to enforce authors of a specific piece of code to respond to the documentation request.

Convention Guide

Character Encoding

To facilitate cross-platform compatibility, please use UTF-8 or ASCII. Note that UTF-8 is backwards compatible with ASCII.

Documentation

Pull requests with no documentation will be rejected. We believe documentation is good and integral to the success of a community software project. However, we recognize that everyone has different expectations and opinions on code documentation. Self-documenting code should be sufficient in most cases but the use of inline comments to organize blocks of code are encouraged.

End of Line

To facilitate cross-platform compatibility, please use unix style line endings of LF (\n). For three popular text editors, here are instructions on how to enable LF endings.

System Environment Variables

Persistent system environment variables are used to when referencing across and within repositories. They should follow a naming convention of AEM_TYPE_DESCRIPTION.

  • Persistent system variables should be written using all capital letters
  • Strings should be delimitated by an underscore, _
  • A prefix of AEM should always be used for software within this organization
  • The second string should describe what the variable references. Use DIR for directories; FILE for files; and SCRIPT for shell scripts.
  • The third string should provide additional descriptive information.

Variable Names

  • When applicable, variable names should include units, such as speed_kt or el_ft_msl.
  • Delimiter-separated words should use an underscore, _
  • Variable names should be short yet meaningful. The choice of a variable name should be mnemonic — that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary “throwaway” variables. Common names for temporary variables are i, j, k.

Units

We employ units commonly used by the United States aviation community. We strongly recommend converting to these units as soon as possible when reading in data. We discourage converting to a different units within stand alone functions or as part of intermediate code. Excess use of non U.S. aviation units may prompt a rejection of a pull request.

For more information, refer to Aviation Stackexchange: “Why doesn’t the aviation industry use SI units?” and “What is the measurement system used in the aviation industry?”

Dimension Unit
time second (s)
length - altitude & elevation foot (ft)
length - longitudinal and lateral distance foot (ft) or nautical mile (nm)
speed - vertical rate foot per second (fps)
speed - airspeed or ground speed knot (kts)
plane angle - course, heading, roll, pitch, yaw degree (deg)
latitude & longitude coordinates decimal degrees (DD)
world geodetic system WGS 84 (EPSG:4326)
mass pound mass (lb)
force pound force (lbf)
temperature degree Fahrenheit (°F)

Colors

To promote accessibility and align with graphic best practices, we recommend a color guidelines proposed by B. Wong that is perceived as reasonably distinct by both normal and color blind individuals. Selecting a widely perceived color scheme is particularly important for peer reviews, as B. Wong notes:

If a submitted manuscript happens to go to three male reviewers of Northern European descent, the chance that at least one will be color blind is 22 percent…The palette of eight colors shown [below] has good overall variability and can be differentiated by individuals with red-green color blindness.

Colors optimized for color-blind individuals

B. Wong, “Points of view: Color blindness,” Nature Methods, vol. 8, pp. 441–441, May 2011. 

@article{wongPointsViewColor2011,
	title = {Points of view: {Color} blindness},
	volume = {8},
	copyright = {2011 Nature Publishing Group},
	issn = {1548-7105},
	shorttitle = {Points of view},
	url = {https://www.nature.com/articles/nmeth.1618},
	doi = {10.1038/nmeth.1618},
	language = {en},
	urldate = {2019-08-27},
	journal = {Nature Methods},
	author = {Wong, Bang},
	month = may,
	year = {2011},
	pages = {441--441},
	}


Questions about the source code

Please contact the administrators at encounter-model-ml-admin@mit.edu. As the encounter models transition to a more community driven effort, a separate mailing list for code discussion may be created.