We encourage the use of the GitHub Issues for bug report, new feature requests, etc. To streamline reporting, issues will only be enabled for the em-overview repository.
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.
- How to contribute
This project and everyone participating in it is governed by the Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].
No public technology roadmap for development is available yet. As the encounter models transition to a more community-focused model, this may change.
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.
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.
- The repository required for development is identified in airspace-encounter-models
- This repository is forked by the mit-ll organization.
- 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).
- Development is conducted using branches on the enterprise clone.
- When development is over, the clone will be released review according to internal policies.
- Once the clone is approved for public release, changes will be pushed to the public fork.
- A pull request will be opened to contribute back to the original.
- The encounter model administrators will review the pull request and either accept or reject it.
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.
- 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.
- 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.
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.
According to Wikipedia and IEEE 829, a software feature is a:
A distinguishing characteristic of a software item (e.g., performance, portability, or functionality.
- 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.
- 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 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.
To facilitate cross-platform compatibility, please use UTF-8 or ASCII. Note that UTF-8 is backwards compatible with ASCII.
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.
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.
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
AEMshould always be used for software within this organization - The second string should describe what the variable references. Use
DIRfor directories;FILEfor files; andSCRIPTfor shell scripts. - The third string should provide additional descriptive information.
- When applicable, variable names should include units, such as
speed_ktorel_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.
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) |
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.
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},
}Please contact the administrators at [email protected]. As the encounter models transition to a more community driven effort, a separate mailing list for code discussion may be created.
DISTRIBUTION STATEMENT A. Approved for public release. Distribution is unlimited.
This material is based upon work supported by the Federal Aviation Administration under Air Force Contract No. FA8702-15-D-0001.
Any opinions, findings, conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the Federal Aviation Administration.
This document is derived from work done for the FAA (and possibly others), it is not the direct product of work done for the FAA. The information provided herein may include content supplied by third parties. Although the data and information contained herein has been produced or processed from sources believed to be reliable, the Federal Aviation Administration makes no warranty, expressed or implied, regarding the accuracy, adequacy, completeness, legality, reliability or usefulness of any information, conclusions or recommendations provided herein. Distribution of the information contained herein does not constitute an endorsement or warranty of the data or information provided herein by the Federal Aviation Administration or the U.S. Department of Transportation. Neither the Federal Aviation Administration nor the U.S. Department of Transportation shall be held liable for any improper or incorrect use of the information contained herein and assumes no responsibility for anyone’s use of the information. The Federal Aviation Administration and U.S. Department of Transportation shall not be liable for any claim for any loss, harm, or other damages arising from access to or use of data or information, including without limitation any direct, indirect, incidental, exemplary, special or consequential damages, even if advised of the possibility of such damages. The Federal Aviation Administration shall not be liable to anyone for any decision made or action taken, or not taken, in reliance on the information contained herein.