From ab6e20867bd02347d1aa53fa68ad10213a470cd9 Mon Sep 17 00:00:00 2001 From: Frank Kopp <frank@familie-kopp.de> Date: Thu, 7 Nov 2024 13:16:10 +0100 Subject: [PATCH] Update dev guide and setup env --- docs/dev-corner/dev-guide/contribute.md | 79 +++++++++++++------ docs/dev-corner/dev-guide/index.md | 2 +- docs/dev-corner/dev-guide/resources.md | 41 ++++++---- .../dev-corner/dev-guide/setup-environment.md | 72 +++++++++++------ 4 files changed, 129 insertions(+), 65 deletions(-) diff --git a/docs/dev-corner/dev-guide/contribute.md b/docs/dev-corner/dev-guide/contribute.md index 2271adf48..57eaa59e0 100644 --- a/docs/dev-corner/dev-guide/contribute.md +++ b/docs/dev-corner/dev-guide/contribute.md @@ -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. @@ -23,9 +23,11 @@ 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) @@ -33,9 +35,11 @@ Make sure to read our [Code of Conduct](https://github.com/flybywiresim/aircraft 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). @@ -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. @@ -85,13 +98,16 @@ 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 @@ -99,23 +115,34 @@ Additionally, a few practices are straight up forbidden: 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. diff --git a/docs/dev-corner/dev-guide/index.md b/docs/dev-corner/dev-guide/index.md index cdca47a37..d9ddf2683 100644 --- a/docs/dev-corner/dev-guide/index.md +++ b/docs/dev-corner/dev-guide/index.md @@ -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 diff --git a/docs/dev-corner/dev-guide/resources.md b/docs/dev-corner/dev-guide/resources.md index 5661ede3c..132c5e9ee 100644 --- a/docs/dev-corner/dev-guide/resources.md +++ b/docs/dev-corner/dev-guide/resources.md @@ -5,7 +5,8 @@ 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 @@ -13,25 +14,31 @@ 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 @@ -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. \ No newline at end of file +- [P3D XML Gauge Reference](http://www.prepar3d.com/SDK/SimObject%20Creation%20Kit/Panels%20and%20Gauges%20SDK/creating%20xml%20gauges.html) + still applies to FS2020. \ No newline at end of file diff --git a/docs/dev-corner/dev-guide/setup-environment.md b/docs/dev-corner/dev-guide/setup-environment.md index 251be0ec3..9b4ac30fb 100644 --- a/docs/dev-corner/dev-guide/setup-environment.md +++ b/docs/dev-corner/dev-guide/setup-environment.md @@ -15,11 +15,13 @@ Also, some git client is necessary to interact with the GitHub repository. Either use a standalone git client (terminal or UI based) or one integrated into your editor. -Make sure you are familiar with the basics of working with git/GitHub. The GitHub [Quickstart](https://docs.github.com/en/get-started/quickstart){target=new} documentation is a great help. +Make sure you are familiar with the basics of working with git/GitHub. The GitHub +[Quickstart](https://docs.github.com/en/get-started/quickstart){target=new} documentation is a great help. ### Docker -FlyByWire provides a preconfigured docker container that has all necessary tools included and preconfigured to compile the aircraft. +FlyByWire provides a preconfigured docker container that has all necessary tools included and preconfigured to compile +the aircraft. To use this, you need to download and install [Docker](https://docs.docker.com/get-docker/){target=new} here. @@ -27,59 +29,80 @@ Use either WSL2 or HyperV backend work, but the latter is faster. ### Editor or IDE -Most of our team works with either Visual Studio Code or IntelliJ IDEA-based IDEs for development. Obviously, your choice is yours as long as the resulting code conforms to our standards. +Most of our team works with either Visual Studio Code or IntelliJ IDEA-based IDEs for development. Obviously, your +choice is yours as long as the resulting code conforms to our standards. + +For Visual Studio Code, we recommend installing the following extensions: +[vscode eslint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) + +It's recommended to set gitbash as your default shell in vscode ## Getting the source code -To work on the A32NX project, you need to create a fork ( [GitHub fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo){target=new)}) of the [aircraft repository](https://github.com/flybywiresim/aircraft). +To work on the A32NX project, you need to create a fork ( +[GitHub fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo){target=new)}) of the +[aircraft repository](https://github.com/flybywiresim/aircraft). -Clone this fork to your local environment. You can use the command line git or a UI-based git to do this. On the command line, go to your projects folder and clone it into that folder. +Clone this fork to your local environment. You can use the command line git or a UI-based git to do this. On the command +line, go to your projects folder and clone it into that folder. ``` git clone https://github.com/flybywiresim/aircraft.git +cd aircraft +git submodule update --init +.\scripts\dev-env\run.cmd ./scripts/setup.sh ``` -You now have a copy of the aircraft repository on your local machine to review and change the source code. The subfolder `./fbw-a320nx` contains the A32NX source code. +You now have a copy of the aircraft repository on your local machine to review and change the source code. -## Compiling the source +The setup.sh is configuring the build process and is sometimes necessary when you changed branches which for example use +a different Nodes configuration. -To compile the source code into a package you can install into the Microsoft Flight Simulator Community folder, we have prepared a few scripts you need to run, which in turn use the Docker container mentioned above to compile the aircraft add-on. +## Compiling the source +To compile the source code into a package you can install into the Microsoft Flight Simulator Community folder, we have +prepared a few scripts you need to run. These use the Docker container mentioned above to compile the aircraft +add-on. ```powershell title="PowerShell or Cmd Prompt" cd aircraft -.\scripts\dev-env\run.cmd ./scripts/setup.sh .\scripts\dev-env\run.cmd ./scripts/build.sh ``` +To build only the A32NX or the A380X, change build.sh to build_a32nx.sh or build_a380x.sh. To build the A380X with 4K +textures instead of maximum quality (8K), add the -4k flag at the end of the command. -```bash title="git bash or other *nix shells on Windows" -cd aircraft -./scripts/dev-env/run.cmd ./scripts/setup.sh -./scripts/dev-env/run.cmd ./scripts/build.sh -``` - -The setup.sh is configuring the build process and is sometimes necessary when you changed branches which for example use a different Nodes configuration. +If you are using WSL, ensure that the Vmmem process is not memory-limited. At least 10GB of memory is the recommended +setting. This can be configured in C:\<user>\.wslconfig. -The build.sh is actually using the docker container to compile and build the add-on into the folder `flybywire-aircraft-a320-neo`. +The build.sh is actually using the docker container to compile and build the add-on(a) into the folder +`fbw-a32nx/out/flybywire-aircraft-a320-neo` or `fbw-a380x/out/flybywire-aircraft-a380` respectively. !!! note "Compiling on Linux (incl. WSL)" You should use run.sh instead of run.cmd if you are on Linux/WSL. - If you are using WSL, ensure that the Vmmem process is not memory limited. At least 10 GB of memory is the recommended setting. This can be configured in C:\<user>\.wslconfig. + If you are using WSL, ensure that the Vmmem process is not memory limited. At least 10 GB of memory is the + recommended setting. This can be configured in C:\<user>\.wslconfig. !!! tip "Create working branches" - We recommend when making changes on your fork, you create a new branch, titled with the change you're looking to make or something similar. + We recommend when making changes on your fork, you create a new branch, titled with the change you're looking to + make or something similar. -After a successful build, it is possible to copy the `flybywire-aircraft-a320-neo` folder into your Community folder and use the compiled A32NX in your simulator. See next chapter for a more convenient way to update the add-on after a compile. +After a successful build, it is possible to copy the `fbw-a32nx/out/flybywire-aircraft-a320-neo` or +`fbw-a380x/out/flybywire-aircraft-a380` folders into your Community folder and use the compiled A32NX in your simulator. +See the next chapter for a more convenient way to update the add-on after a compilation. !!! warning "Important step!" Make sure you remove any existing copy of the aircraft from your community folder before doing this. ## Linking Dev folder to Community folder -To avoid having to copy the `flybywire-aircraft-a320-neo` folder after every compile, it is possible to use a so called symlink from your Community folder to your compiled `flybywire-aircraft-a320-neo` folder. +To avoid having to copy the `flybywire-aircraft-a320-neo`/`fbw-a380x/out/flybywire-aircraft-a380` folders after every +compile, it is possible to use a so-called symlink from your Community folder to your compiled +`flybywire-aircraft-a320-neo`/`fbw-a380x/out/flybywire-aircraft-a380` folder. -To create your symlink, open your command terminal and run the below command, substituting the correct file paths with your community folder, and the 'flybywire-aircraft-a320' folder from your new project. +To create your symlink, open your command terminal and run the below command, substituting the correct file paths with +your community folder, and the `flybywire-aircraft-a320`/`fbw-a380x/out/flybywire-aircraft-a380` folder from your new +project. !!! warning "Important step!" Make sure you remove any existing copy of the aircraft from your community folder before doing this. @@ -95,9 +118,10 @@ mklink /J C:\Users\USERNAME\AppData\Local\Packages\Microsoft.FlightSimulator_8we If this works, you'll receive the response: -"Junction created for \[Community folder] \[Project Folder]" from the terminal. +`Junction created for \[Community folder] \[Project Folder]` from the terminal. -Now you've compiled and symlinked your GitHub fork to your community folder, you should be able to load into the aircraft as normal. +Now you've compiled and symlinked your GitHub fork to your community folder, you should be able to load into the +aircraft as normal. !!! info "" Open MSFS and check everything is working with your compiled branch before progressing.