diff options
Diffstat (limited to 'docs/development')
| -rw-r--r-- | docs/development/README.md | 13 | ||||
| -rw-r--r-- | docs/development/contributing-code-to-northstar.md | 80 | ||||
| -rw-r--r-- | docs/development/northstarlauncher.md | 7 | ||||
| -rw-r--r-- | docs/development/northstarmasterserver/README.md | 15 | ||||
| -rw-r--r-- | docs/development/northstarmasterserver/deploy.md | 27 | ||||
| -rw-r--r-- | docs/development/releases.md | 69 | ||||
| -rw-r--r-- | docs/development/repositories/README.md | 28 | ||||
| -rw-r--r-- | docs/development/repositories/atlas.md | 7 | ||||
| -rw-r--r-- | docs/development/repositories/northstarmods.md | 7 | ||||
| -rw-r--r-- | docs/development/reviewing.md | 69 | ||||
| -rw-r--r-- | docs/development/testing.md | 113 |
11 files changed, 435 insertions, 0 deletions
diff --git a/docs/development/README.md b/docs/development/README.md new file mode 100644 index 0000000..56acd02 --- /dev/null +++ b/docs/development/README.md @@ -0,0 +1,13 @@ +--- +description: >- + Instructions on how to make changes to Northstar source code, build, and run + it. +--- + +# Development + +Check the following page for information about different code repositories Northstar uses + +{% content-ref url="repositories/" %} +[repositories](repositories/) +{% endcontent-ref %} diff --git a/docs/development/contributing-code-to-northstar.md b/docs/development/contributing-code-to-northstar.md new file mode 100644 index 0000000..98cf770 --- /dev/null +++ b/docs/development/contributing-code-to-northstar.md @@ -0,0 +1,80 @@ +--- +description: Useful information when contributing to Northstar +--- + +# Contributing code to Northstar + +{% hint style="info" %} +WIP +{% endhint %} + +## Guidelines + +For a pull request to be merged, it has to be reviewed first. In order to make the review process as smooth as possible and therefore ensuring quick merging of your pull request, keep the following things in mind: + +- If the changes you made can be summarised in a screenshot or screenrecording, make sure to add one to quickly give a reviewer an idea what your pull request is about. +- Please use a sensible title for your pull request. We squash commits when merging and as such your pull request title will be used as the commit message. We can of course edit it before merging but using a sensible title for your PR both makes it easier to understand what it is about and saves us from having to edit the title before merging. +- Please describe the changes you made. The easier it is to understand what you changed, the higher the chances of your PR being merged (in a timely manner). +- If you made multiple independent changes, please make a new PR for each one. This prevents cases where your PR is being blocked from merging by a bug one of the changes you made. + +## Tips and tricks + +An example of a well-formatted PR description: + +{% embed url="https://github.com/R2Northstar/NorthstarMods/pull/392" %} + +To get the cropped GIFs of a screenrecording: + +1. Use your screenrecording tool of choice (OBS/ShadowPlay/...) to record the clip +2. Cut it down to just the moment you want to show using [Avidemux](http://www.avidemux.org/), [VLC](https://www.videolan.org/vlc/), etc. +3. Use a site like [https://ezgif.com/video-to-gif](https://ezgif.com/video-to-gif) for cropping and turning it into a GIF \ + (The linked site has not been vetted, use at own risk) +4. Upload GIF to GitHub pull request description by just pasting it at the appropriate location. + +### Avoiding "PR hell" + +_"PR hell"_ is what contributors refer to when a pull request is stuck as pending without any indication for progress. + +There can be a variety reasons for this. Whether it's because the pull request was overlooked, the changes are too big that anyone actually dares looking at it, or simply every reviewer is too busy at the moment, not getting a response on something you put a lot of work into is a terrible experience. + +While we are continuously working on improving the experience and recruiting more reviewers, here's a few tips to avoid _"PR hell"_. + +**Make sure your PR is easy to review:** + +If you are submitting a new feature, highlight it with screenshots, screenrecordings, GIFs etc. If you can make your change look interesting, it highly increases the chance of someone becoming interested in getting it merged. + +If you are submitting a bug fix, make sure to mention the steps to reproduce the bug and that the same steps no longer cause the bug on your fixed version. + +Finally, smaller code changes are easier to review than bigger ones, which brings us to: + +**Keep PRs concise and focused on a specific issue:** + +While working on code to create some feature or fix some issue you might come across some other things you also want to change. While this is fine, it's highly recommended to split out these changes into separate PRs. + +Having lots of small PRs is way easier to review and work with than one big PR. Further if there's an issue with one of the changes it does not block the whole big PR but just one of the small ones. + +Smaller changes are also way easier to review and test. + +If you're working on a big feature that introduces lots of changes (let's say you implemented an entire party system into Northstar) a recommended approach is to PR your big change so that feature can be easily observed and interest generated. \ +Then ask which parts should be turned into separate pull requests, PR those, and link them with your big PR. As the the smaller PRs are merged, the diff of the big PR should shrink overtime until concise enough to be merged all at once. + +Just make sure to resolve merge conflicts when the smaller PRs are merged ;) + +**Ping previous author:** + +Especially when you fix a bug in existing code, you usually modify code that was written by someone else. In that case the best person to review that code is the original author. So `@` ping them in the pull request! + +You can use tools like [`git blame`](https://www.git-scm.com/docs/git-blame) (on the web via GitHub, in vscode via gitlens, via command-line, ...) to see who previously wrote the code. + + +**Ping for updates:** + +Sometimes it can happen that a pull request simply gets lost in the sea of other pull requests. If you haven't received a response in a while on a pull request that has already received some responses, just leave a comment on it (even if it's just "bump"). This will send a notification to everyone that responded previously in the PR and likely cause them to respond again. + +Similarly, you can also check merged pull requests and see who reviewed/merged them and ping that person individually. + +**If all else fails:** + +If despite all your attempts you are still not seeing responses, your last resort is always to ask around in `#development` on the Northstar Discord. We really do not want to see anyone become frustrated with the lack of responses on their pull request and close it in frustration. As such please reach out earlier rather than later. + +We will try our best to look at it <3 diff --git a/docs/development/northstarlauncher.md b/docs/development/northstarlauncher.md new file mode 100644 index 0000000..89aeca4 --- /dev/null +++ b/docs/development/northstarlauncher.md @@ -0,0 +1,7 @@ +# NorthstarLauncher + +### Setup + +Build instructions for the launcher can be found here: + +{% embed url="https://github.com/R2Northstar/NorthstarLauncher/blob/main/BUILD.md" %} diff --git a/docs/development/northstarmasterserver/README.md b/docs/development/northstarmasterserver/README.md new file mode 100644 index 0000000..d6c94b5 --- /dev/null +++ b/docs/development/northstarmasterserver/README.md @@ -0,0 +1,15 @@ +# NorthstarMasterServer + +{% hint style="warning" %} +The old NodeJS master server has been replaced in favour of the Go rewrite called Atlas. +{% endhint %} + +## Introduction + +The master server is responsible for centralizing game servers created by players, it also verifies that connecting players own an Origin account with Titanfall 2. + +There's no need to host your own master server to play games with other people, you can use [direct connect](../../using-northstar/direct-connect.md) or just setup a [normal server](../../hosting-a-server-with-northstar/basic-listen-server.md) that announces itself to `northstar.tf`. This tutorial is aimed for those who want to contribute improvements to the code or test their own changes to the project. + +## Contents + +* [Deploy](deploy.md) diff --git a/docs/development/northstarmasterserver/deploy.md b/docs/development/northstarmasterserver/deploy.md new file mode 100644 index 0000000..c384730 --- /dev/null +++ b/docs/development/northstarmasterserver/deploy.md @@ -0,0 +1,27 @@ +# Deploy + +## Development + +A Development Master Server uses http requests, it should be used for development purposes on your local machine. + +### Installation steps + +1. Clone [NorthstarMasterServer](https://github.com/R2Northstar/NorthstarMasterServer). +2. Copy the default [dev.env](https://github.com/R2Northstar/NorthstarMasterServer/blob/main/dev.env) to `.env` replace the ip with `127.0.0.1`. +3. Run `npm install` && `npm run watch`. + +Your master server is now running, to connect to it you need to change some configuration files. + +Northstar default masterserver is https://northstar.tf, to point to a new location you need to modify this URL in the `autoexec_ns_server.cfg` and `autoexec_ns_client.cfg` config files. + +### Enabling HTTPS + +HTTPS should be used if you plan for other people to use your master server. It can be enabled pretty easy with [Caddy](https://caddyserver.com/). Download a Caddy binary and create a `Caddyfile` with the following content: + +``` +{$SHORTDOMAIN:localhost} { + reverse_proxy http://127.0.0.1:8080 +} +``` + +After configuring your DNS domain you can run it with `SHORTDOMAIN=example.com caddy run`. Caddy will automatically generate and maintain your certificates for you, check its documentation for more info: https://caddyserver.com/docs/ diff --git a/docs/development/releases.md b/docs/development/releases.md new file mode 100644 index 0000000..44f502a --- /dev/null +++ b/docs/development/releases.md @@ -0,0 +1,69 @@ +--- +description: >- + Information intended mostly for internal use on what to consider when making + new releases +--- + +# Releases + +{% hint style="info" %} +WIP +{% endhint %} + +## General + +CI on Northstar release repo builds versioned release if tag is pushed. It checks Launcher and Mods for same tag and builds those versions. \ +Therefore make sure to push tags of Mods and Launcher first. + +CI also pushes release directly to Thunderstore as a mod called [`Northstar`](https://northstar.thunderstore.io/package/northstar/Northstar/). \ +If it's a release-candidate with the `-rcX` suffix, it will instead get pushed to Thunderstore as [`NorthstarReleaseCandidate`](https://northstar.thunderstore.io/package/northstar/NorthstarReleaseCandidate/). + +### Git commands for tags: + +**For release candidates:** + +``` +git tag vX.Y.Z-rcN +git push origin vX.Y.Z-rcN +``` + +Example: + +``` +git tag v1.8.0-rc1 +git push origin v1.8.0-rc1 +``` + +**For actual releases** + +``` +git tag vX.Y.Z +git push origin vX.Y.Z +``` + +Example: + +``` +git tag v1.8.0 +git push origin v1.8.0 +``` + +## Version numbering + +In general, Northstar tries to follow [semantic versioning](https://semver.org/). This means version numbers are `MAJOR.MINOR.PATCH`, where + +- `MAJOR` is updated for breaking changes +- `MINOR` is updated for changes that are backwards compatible +- `PATCH` is updated for fixes that are backwards compatible + +Semantic versioning is however not followed exactly. For example, to ship out smaller features faster they have been included in patch releases. Similarly, there have been smaller breaking changes, yet at the time of writing the major version number so far has never been updated. + +The reason for this is mostly due to player expectations. Players expect the change from `1.0` to `2.0` to be big. As such, the plan for the near future is to update the major version, once we have a bigger feature ready to release that brings us closer to vanilla in terms of missing features (e.g. _Frontier Defense_). + +Once `2.0` has been released, expectations for `3.0` tend to be lower as the number is no longer "doubled". Past `3.0`, proper semver can probably be employed without hampering player expectations. + + +## Best practices: + +- Make at least one release candidate and test it before actual release. +- Release should also only ever be latest release candidate but tagged as release to avoid introducing new bugs. diff --git a/docs/development/repositories/README.md b/docs/development/repositories/README.md new file mode 100644 index 0000000..bce048e --- /dev/null +++ b/docs/development/repositories/README.md @@ -0,0 +1,28 @@ +# Repositories + +Northstar is split over multiple git repositories that fulfill different functions. + +* [Atlas](https://github.com/R2Northstar/Atlas):\ + The next-gen master server for Northstar +* [Northstar](https://github.com/R2Northstar/Northstar):\ + Contains compiled and packaged releases +* [NorthstarLauncher](https://github.com/R2Northstar/NorthstarLauncher):\ + Contains the source for the launcher used to modify the Titanfall|2 install to allow mods to be loaded. +* [NorthstarMods](https://github.com/R2Northstar/NorthstarMods):\ + Contains the standard mods shipped with Northstar to allow joining and hosting custom servers. +* [NorthstarMasterServer](https://github.com/R2Northstar/NorthstarMasterServer):\ + Contains the source for the old master server used to authenticate clients, display the server browser list, and connect clients to community hosted servers. +* [NorthstarDiscordRPC](https://github.com/R2Northstar/NorthstarDiscordRPC):\ + Contains plugin to integrate Northstar with Discord's SDK to enable rich presence. +* [NorthstarNavs](https://github.com/R2Northstar/NorthstarNavs):\ + Contains custom navmesh files to use with TItanfall 2 AI +* [NorthstarStubs](https://github.com/R2Northstar/NorthstarStubs):\ + Contains D3D11 and GFSDK stubs for the Northstar dedicated server. +* [NorthstarTF](https://github.com/R2Northstar/NorthstarTF):\ + The Northstar website. +* [NorthstarWiki](https://github.com/R2Northstar/NorthstarWiki):\ + The repository for this wiki. +* [ModdingDocs](https://github.com/R2Northstar/ModdingDocs):\ + Contains guides and tutorials on how to mod using Northstar + +Check the subpages of this wiki for additional information about some of these repositories. diff --git a/docs/development/repositories/atlas.md b/docs/development/repositories/atlas.md new file mode 100644 index 0000000..9f67c75 --- /dev/null +++ b/docs/development/repositories/atlas.md @@ -0,0 +1,7 @@ +--- +description: A new Northstar master server written in Go +--- + +# Atlas + +TODO diff --git a/docs/development/repositories/northstarmods.md b/docs/development/repositories/northstarmods.md new file mode 100644 index 0000000..1798661 --- /dev/null +++ b/docs/development/repositories/northstarmods.md @@ -0,0 +1,7 @@ +--- +description: Core squirrel mods +--- + +# NorthstarMods + +TODO diff --git a/docs/development/reviewing.md b/docs/development/reviewing.md new file mode 100644 index 0000000..a9d8934 --- /dev/null +++ b/docs/development/reviewing.md @@ -0,0 +1,69 @@ +--- +description: >- + This pages describes how to review PRs to ensure quick and efficient merging. + It is written for both novices and people with experience with GitHub and code + review in general. +--- + +# Reviewing + +For new pull requests to be merged into any of the Northstar repos, they need to reviewed to reduce the changes of introducing bugs as well as ensuring that in case of a feature it's something the community actually wants. + +### Process + +For a review there's two major parts **code review** and **testing**. + +It's not necessary to do both when reviewing as long as you mention what you did when leaving the review comment on GitHub. + +#### Code review + +For code review head to the _"Files changed"_ section of the PR. + + + +From there you can select the line(s) you want to leave a comment on. + + + +Type in your comment and click on _"Start a review"_. + + + +Note that this will **NOT** post your comment immediately! Add any remaining comments to other lines of code, then head to the _Finishing up_ section of this wiki page to see how to post your code review. + + + +#### Testing + +For testing a PR, refer to the following page + +{% content-ref url="../testing.md" %} +[testing.md](./testing.md) +{% endcontent-ref %} + +The TL;DR is to test the aspect that has been changed. + +#### Finishing up + +After you performed the testing and/or code review leave a final comment by clicking on _"Finish your review"_ on the top right of the _"Files changed"_ page of the PR. + + + +In your final comment make sure to mention what you did, e.g. which aspects of the change you tested for or what you considered during code review (formatting, edge cases, ...). The more detailed this part is the easier it is for other reviewers to tell which aspects they can skip during reviewing to speed up the process. + +After leaving your comment, select the type of feedback. + +* **Comment**: General remarks, use if neither of the later two applies. +* **Approve**: You found no issues when looking at the code or during testing. +* **Request changes**: Either something in the code doesn't look right or you found bugs during testing. + +{% hint style="warning" %} +Approval reviews should **always** contain information about what parts of the code you looked at or tested. Approvals without comment or a single _LGTM_ are not useful and will be dismissed. \ +Some exceptions to this rule are e.g. approving a single line comment typo fix, though even than the review should say something along the lines of "LGTM as it's just single line typo fix in a comment". In a nutshell it should be obvious to a future reader why you approved a PR without the reader having to look at the file diff first. + +Contributors with reviewer access may see their role removed should they leave (multiple) empty/_"LGTM"_ reviews. + +If you want to "approve" a pull request because you like the feature it implements, please opt for simply giving the PR a "👍" reaction instead. +{% endhint %} + +Finally, click on _"Submit review"_. Your review is now publicly visible, congrats! :D diff --git a/docs/development/testing.md b/docs/development/testing.md new file mode 100644 index 0000000..8ba01ff --- /dev/null +++ b/docs/development/testing.md @@ -0,0 +1,113 @@ +--- +description: >- + Instructions regarding testing new features, directed at both developers and + maintainers +--- + +# Testing + +{% hint style="info" %} +This section is very much still WIP. Feel free to help expand it. +{% endhint %} + +## Developers & Contributors + +This section applies to you if you're opening a pull request to any of the Northstar repos. + +Whatever your change includes, whether a bug fix or a new feature make sure to test it appropriately. + +This means if your change is a bug fix, it's recommend you first make sure you can reproduce the bug. Then after making the necessary changes to fix it, test it using the same method you used to originally confirm the bug.\ +When you're opening a pull request, make sure to mention how to reproduce the bug, so that reviewers can confirm that your chance indeed fixed the issue. + +If your change is a new feature, make sure to test both that the newly added functionality performs as expected, as well as ensuring that it doesn't introduce any form of regression bugs. This means, testing anything that might be affected by your new feature. + +## Maintainers + +This section applies to you if you're someone who's able to merge PRs in any of the repos of the Northstar GitHub org as well as when simplying performing reviews, even without being able to actually merge a PR. + +When reviewing pull requests on GitHub, make sure to checkout the changes made by a PR locally and test it there. In particular, test the parts of the code that are touched by a PR. + +After testing, make sure to mention the steps tested in your review. + +## Acquiring necessary files + +### FlightCore developer tools + +You can use FlightCore to essentially 1-click install any pull request to [NorthstarMods](https://github.com/R2Northstar/NorthstarMods/) and [NorthstarLauncher](https://github.com/R2Northstar/NorthstarLauncher/). + +The tool is still being improved upon but already more than usable. Check its README for instructions: + +{% embed url="https://github.com/R2NorthstarTools/FlightCore/blob/main/docs/DEV-TOOLS.md" %} + + +### Manually + +#### NorthstarLauncher + +Before starting, make sure you have a **working and up-to-date Northstar install** and you're **logged into GitHub with your GitHub account** (downloading files from CI only works while logged into any GitHub account)! + +1. Head to the bottom of the page of the PR and click on "_Show all checks_"  +2. For "_CI / build (pull\_request)_" click on "_Details_"\ +   +3. From here click on "_Summary_"\ +   +4. And then click on "_NorthstarLauncher-XXXXXXX_"\ +   +5. Once downloaded, open the zip and copy `Northstar.dll` and `NorthstarLauncher.exe` to your Titanfall2 folder, overwriting the existing DLL and EXE in there. + +Alternatively, compiling the PR'd code from source is also an option. For this, refer to [northstarlauncher.md](northstarlauncher.md "mention") + +#### NorthstarMods + +Click on the source branch of the PR + + + +Click on _"Code"_ and then on _"Download ZIP"_ + + + +From there copy over all the `Northstar.XXXXX` folders into your mods folder in your TItnafall2 install the same way you would manually install mods. + +## Tips and toolkits + +(might require `sv_cheats 1`) + +**Spawn titan/grunt:** + +* For titan: `ent_create npc_titan; ent_fire !picker setteam 2` +* For grunt: `ent_create npc_soldier; ent_fire !picker setteam 2` + +**Give free kill / build up titan/core meter** + +`script AddPlayerScore(GetPlayerArray()[0], "KillPilot")` + +where `GetPlayerArray()[0]` should point to the player you want to give kill/meter. + +**Add fake lag for network testing** + +`net_fakelag 200` -> 200ms network lag + +``` +] find net_fake +[info] "net_fakelag" = "0" ( CHEAT ) - Lag all incoming network data (including loopback) by this many milliseconds. +[info] "net_fakeloss" = "0" - Simulate packet loss as a percentage (negative means drop 1/n packets) +[info] "net_fakelag_clientOnly" = "1" ( CHEAT ) - Fakelag won't affect the server, only clients +[info] "net_fakelagjitter" = "0" - Jitter net_fakelag packet time +``` + +**Joining same server multiple times with same accounts** + +By default duplicate accounts are blocked by server. Use `-allowdupeaccounts` when starting server to allow duplicate accounts. From there you can launch multiple clients on the same account and connect them to the server. + +**Quickly switch map** + +Use `map <map name>` to quickly switch map.\ +Example: `map mp_glitch` + +List of maps can be found [here](../hosting-a-server-with-northstar/dedicated-server/#maps) + +**Speed-up/slow-down game** + +Use `host_timescale <factor>` to speed-up or slow-down the game.\ +For example `host_timescale 10` speeds up game by factor of `10`. Set to `1` to go back to default. |