Skip to content

Commit

Permalink
Update dev guide and setup env
Browse files Browse the repository at this point in the history
  • Loading branch information
@frankkopp
frankkopp committed Nov 11, 2024
1 parent 8719dee commit ab6e208
Show file tree
Hide file tree
Showing 4 changed files with 129 additions and 65 deletions.
79 changes: 53 additions & 26 deletions docs/dev-corner/dev-guide/contribute.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ description: Overview of the FlyByWire Contribution Guidelines

# Contribution Guidelines

Welcome to the FlyByWire Aircraft project repository. Thank you for your interest in contributing to the project. Full details and
guidelines on how to ensure this project is managed well are included below.
Welcome to the FlyByWire Aircraft project repository. Thank you for your interest in contributing to the project. Full
details and guidelines on how to ensure this project is managed well are included below.

As this is an open-source project, anyone is free to contribute as much or as little as they like.

Expand All @@ -23,19 +23,23 @@ If you're looking for tools and tips to help you develop, see [Development Resou

## Expectations

As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues
, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, issues and other contributions that are not aligned to this Code of Conduct.
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, issues and
other contributions that are not aligned to this Code of Conduct.

Make sure to read our [Code of Conduct](https://github.com/flybywiresim/aircraft/blob/master/CODE_OF_CONDUCT.md)

## Pull Requests

We welcome pull requests with fixes and improvements to the project.

If you wish to add a new feature or you spot a bug that you wish to fix, **please open an issue for it first** on the [FBW Aircraft issue tracker](https://github.com/flybywiresim/aircraft/issues).
If you wish to add a new feature or you spot a bug that you wish to fix, **please open an issue for it first** on the
[FBW Aircraft issue tracker](https://github.com/flybywiresim/aircraft/issues).

The work-flow for submitting a new pull request is designed to be simple, but also to ensure consistency from **all** contributors:
The work-flow for submitting a new pull request is designed to be simple, but also to ensure consistency from **all**
contributors:

- Fork the project into your personal space on GitHub.com.
- Create a new branch (with a clear name of what is being changed).
Expand All @@ -45,31 +49,40 @@ The work-flow for submitting a new pull request is designed to be simple, but al
- Push the commit(s) to your fork.
- Submit a pull request (PR) to the master branch.
- The PR title should describe the change that has been made.
- Follow the PR template and write as much detail as necessary for your changes, and include documents/screenshots if needed.
- Follow the PR template and write as much detail as necessary for your changes, and include documents/screenshots if
needed.
- Be prepared to answer any questions about your PR when it is reviewed for acceptance.

**Please** keep your changes in a single PR as small as possible (relating to one issue) as this makes it easier to review and accept. Large PRs with a small error will prevent the entire PR from being accepted.
**Please** keep your changes in a single PR as small as possible (relating to one issue) as this makes it easier to
review and accept. Large PRs with a small error will prevent the entire PR from being accepted.

**Ensure** that you include a CHANGELOG with your PR.

## Helping others

Please help other contributors to the project wherever you can, as people all start somewhere. If you require assistance or wish to provide assistance, you can ask/answer questions on the [#dev-support](https://discord.gg/v3jAxJpwZm){target=new} channel on discord.
Please help other contributors to the project wherever you can, as people all start somewhere. If you require assistance
or wish to provide assistance, you can ask/answer questions on the [#dev-support](https://discord.gg/v3jAxJpwZm){target=new} channel on discord.

## Finding tasks

The best place to look for possible things where you could contribute is the FBW Aircraft GitHub repository's [Issues List](https://github.com/flybywiresim/aircraft/issues){target=new}.
There you can find open bug reports or feature requests from users or other developers.
The best place to look for possible things where you could contribute is the FBW Aircraft GitHub repository's
[Issues List](https://github.com/flybywiresim/aircraft/issues){target=new}. There you can find open bug reports or
feature requests from users or other developers.

## Issues

If you require **support** with the A32NX, please utilize the channels on our official [Discord](https://discord.gg/flybywire). Issues regarding the features or bugs will not be handled on Discord. Please use GitHub issues to track new features or bugs.
If you require **support** with the A32NX, please utilize the channels on our official
[Discord](https://discord.gg/flybywire). Issues regarding the features or bugs will not be handled on Discord. Please
use GitHub issues to track new features or bugs.

When submitting an issue, there are a few guidelines we'd ask you to respect to make it easier to manage and for others to understand:
When submitting an issue, there are a few guidelines we'd ask you to respect to make it easier to manage and for others
to understand:

- **Search the issue tracker** before you submit your issue - it may already be present.
- When opening an issue, a template is provided for you. Please provide as much information as requested to ensure others are able to act upon the requests or bug reports.
- Please ensure you add screenshots or documentation references for bugs/changes, so we can quickly ascertain if the request is suitable.
- When opening an issue, a template is provided for you. Please provide as much information as requested to ensure
others are able to act upon the requests or bug reports.
- Please ensure you add screenshots or documentation references for bugs/changes, so we can quickly ascertain if the
request is suitable.

**To be 'assigned' an issue**, please comment on the issue itself, letting others know you are working on it.

Expand All @@ -85,37 +98,51 @@ A few guidelines apply:
- However, do not hesitate to write comments when complex logic is used
- Use language-specific docstring tools (JSDoc, rustdoc)
- Maintain separation of concerns
- Do not be afraid to separate code into logical blocks, even if resulting sub-functions are only used locally (while maintaining a reasonable limit)
- (aircraft development specific) Avoid polling - prefer reactive APIs (but remain sure of not introducing state that cannot be externally read)
- Do not be afraid to separate code into logical blocks, even if resulting sub-functions are only used locally (while
maintaining a reasonable limit)
- (aircraft development specific) Avoid polling - prefer reactive APIs (but remain sure of not introducing state that
cannot be externally read)
- Avoid introducing new technologies/languages without talking to the development team

Additionally, a few practices are straight up forbidden:

- Do not use `async/await` without a good reason (it does not make code run faster, unless you are calling threaded APIs like `fetch`)
- Do not use `async/await` without a good reason (it does not make code run faster, unless you are calling threaded APIs
like `fetch`)
- Do not use hungarian notation (b, m, g identifier prefixes)
- Do not perform business logic calculations in presentation code

## Version Control

Our version control approach maintains the following guidelines:

- Commit messages should be short and to the point. The [Angular commit message convention](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format){target=new} is often used and recommended but not enforced at the moment.
- Commit messages should be short and to the point. The
[Angular commit message convention](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format){target=new}
is often used and recommended but not enforced at the moment.
- Merge commits are discouraged in commit histories and disallowed when merging pull requests
- Squash commits are exclusively used for pull request merges
- One approving review from a maintainer is required to merge a pull request
- Positive reports from a number of QA testers (varies depending on the PR scope and size) are required before merging, unless a maintainer judges appropriate to bypass this rule
- Creation of draft pull requests is required when a developer wishes to get working on a project, to avoid duplicate PR situations
- Positive reports from a number of QA testers (varies depending on the PR scope and size) are required before merging,
unless a maintainer judges appropriate to bypass this rule
- Creation of draft pull requests is required when a developer wishes to get working on a project, to avoid duplicate PR
situations

## Testing

If changes are made, they should always be tested to make sure they work as intended and don't conflict with other systems. If you see a pull request open, it's recommended that you test the features that were implemented to check for errors, or whether it works as intended.
If changes are made, they should always be tested to make sure they work as intended and don't conflict with other
systems. If you see a pull request open, it's recommended that you test the features that were implemented to check for
errors, or whether it works as intended.

## References Material (real life aircraft)

Creating a high-fidelity aircraft is a serious task that requires focus and dedication. But more importantly, it's striving for accuracy and realism. Therefore, any change that affects the appearance or behavior of a plane needs to reference real documentation.
Creating a high-fidelity aircraft is a serious task that requires focus and dedication. But more importantly, it's
striving for accuracy and realism. Therefore, any change that affects the appearance or behavior of a plane needs to
reference real documentation.

The maintainer team has the role of deciding if references are suitable for a change. It is understandable that new developers do not have access to in-depth resource material.
The maintainer team has the role of deciding if references are suitable for a change. It is understandable that new
developers do not have access to in-depth resource material.

While material like that is generally not in the possession of new contributors, the development team is always available to confirm your changes or provide you with necessary info.
While material like that is generally not in the possession of new contributors, the development team is always
available to confirm your changes or provide you with necessary info.

Our extensive pool of IRL A320/A380 pilots and aircraft maintenance engineers are also able to answer your questions whenever needed.
Our extensive pool of IRL A320/A380 pilots and aircraft maintenance engineers are also able to answer your questions
whenever needed.
2 changes: 1 addition & 1 deletion docs/dev-corner/dev-guide/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: The Development Guide is dedicated to providing information to effi
projects.
---

<link rel="stylesheet" href="../../../stylesheets/toc-tables.css">
<link rel="stylesheet" href="/stylesheets/toc-tables.css">

# FlyByWire Development Guide

Expand Down
41 changes: 27 additions & 14 deletions docs/dev-corner/dev-guide/resources.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,33 +5,40 @@ description: Resources for working with and on the A32NX and A380X code.

# Resources

On this page, you will find all the necessary resources, links, and documentation you might need to work with and on the A32NX code.
On this page, you will find all the necessary resources, links, and documentation you might need to work with and on the
A32NX code.

## GitHub Repositories

The main GitHub repository for the A32NX aircraft is:

**[https://github.com/flybywiresim/aircraft](https://github.com/flybywiresim/aircraft){target=new}**

The Development version of the FlyByWire A32NX is done in the master branch. Whenever something is merged into the master branch, an automatic build process builds the newest
Development version and uploads it to our CDN, so users can download the latest Development version via the FlyByWire Installer. We have a very strict development, review and
QA process for this version.
The Development version of the FlyByWire A32NX is done in the master branch. Whenever something is merged into the
master branch, an automatic build process builds the newest Development version and uploads it to our CDN, so users can
download the latest Development version via the FlyByWire Installer. We have a very strict development, review and QA
process for this version.

The Stable version is a snapshot (in git terms, a [Tag](https://github.com/flybywiresim/aircraft/tags){target=new}) of the development branch.
The Stable version is a snapshot (in git terms, a [Tag](https://github.com/flybywiresim/aircraft/tags){target=new}) of
the development branch.

The FlyByWire project has other repositories for subprojects like api, msfs-rs, installer, website, docs, etc. Find them [here](https://github.com/orgs/flybywiresim/repositories){target=new}.
The FlyByWire project has other repositories for subprojects like api, msfs-rs, installer, website, docs, etc. Find them
[here](https://github.com/orgs/flybywiresim/repositories){target=new}.

## Support from the FlyByWire Team on Discord

To get additional information and support, please make sure you join our Discord. There are various channels dedicated to supporting developers (in fact, most channels).
To get additional information and support, please make sure you join our Discord. There are various channels dedicated
to supporting developers (in fact, most channels).

[:fontawesome-brands-discord:{: .discord } - **Discord Link**](https://discord.gg/flybywire){target=new}

First get yourself the "programmer" role in [#roles](https://discord.com/channels/738864299392630914/751780817772216401/816730253543604224){target=new}.
First get yourself the "programmer" role in
[#roles](https://discord.com/channels/738864299392630914/751780817772216401/816730253543604224){target=new}.

The most general channel for getting help for development is [#dev-support](https://discord.gg/v3jAxJpwZm){target=new}.

There are many other channels for specific systems or subprojects. If you are working on the flyPad EFB for example, the #efb channel would be an important channel for collaborating and support.
There are many other channels for specific systems or subprojects. If you are working on the flyPad EFB for example, the
#efb channel would be an important channel for collaborating and support.

## Tech Stack

Expand All @@ -49,19 +56,25 @@ Our tech stack includes the following:
| Displays / Avionics | Typescript / React (deprecated) / MSFS Avionics Framework |

- Systems development for aircraft uses Rust and the `msfs-rs` library.
- Avionics programming is done using JavaScript or TypeScript (depending on the project), with the `React.js` rendering library.
- Avionics programming is done using JavaScript or TypeScript (depending on the project), with the `React.js` rendering
library.
- Front-end web or desktop app development uses the same technologies outlined above.
- Server-side development uses `nest.js` for the API and `MySQL` for the database backend.

Knowledge of all items on this list is obviously not necessary, but this can hopefully give you a better insight into what your skills can fit into.
Knowledge of all items on this list is obviously not necessary, but this can hopefully give you a better insight into
what your skills can fit into.

## Tools

A number of tools make development in Microsoft Flight Simulator easier.

- [WebUI-DevKit](https://github.com/dga711/msfs-webui-devkit){target=new} - In-game development overlay for html-ui content. Provides fast reload, console output, and more!
- [devtools-backend-refurb](https://github.com/dga711/devtools-backend-refurb){target=new} - Chrome DevTools server targeting Coherent GT. Gives you DevTools for html-ui content. WARNING: This is still a work in progress, and tends to be very finicky.
- [WebUI-DevKit](https://github.com/dga711/msfs-webui-devkit){target=new} - In-game development overlay for html-ui
content. Provides fast reload, console output, and more!
- [devtools-backend-refurb](https://github.com/dga711/devtools-backend-refurb){target=new} - Chrome DevTools server
targeting Coherent GT. Gives you DevTools for html-ui content. WARNING: This is still a work in progress, and tends to
be very finicky.

## Additional resources

- [P3D XML Gauge Reference](http://www.prepar3d.com/SDK/SimObject%20Creation%20Kit/Panels%20and%20Gauges%20SDK/creating%20xml%20gauges.html) - still applies to FS2020.
- [P3D XML Gauge Reference](http://www.prepar3d.com/SDK/SimObject%20Creation%20Kit/Panels%20and%20Gauges%20SDK/creating%20xml%20gauges.html)
still applies to FS2020.
Loading

0 comments on commit ab6e208

Please sign in to comment.