From 8d00bc61cfc3cfe1759922ea227396cfd8e1a6c5 Mon Sep 17 00:00:00 2001 From: Duck McSouls Date: Sun, 25 Sep 2022 15:37:28 +1000 Subject: [PATCH 1/4] DOC: fix broken URLs Fix 2 broken URLs in the guide on contribution. Each link is meant to point to the dev branch of the project because new contributions should be based on that branch. --- doc/CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index 593055e26..c3498b55c 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -158,7 +158,7 @@ the following rules: - Work in a branch forked from `dev` to isolate the new code - Ensure you have latest from the [game's main - repository](danielyxie/bitburner@dev) + repository](../../../tree/dev) - Rebase your branch if necessary - Run the game locally to test out your changes - When submitting the pull request, make sure that the base fork is @@ -189,7 +189,7 @@ rules: - Work in a branch forked from `dev` to isolate the new code - Ensure you have latest from the [game's main - repository](danielyxie/bitburner@dev) + repository](../../../tree/dev) - Rebase your branch if necessary - When submitting the pull request, make sure that the base fork is _danielyxie/bitburner_ and the base is _dev_. From 31a7aa74ebaa07a34fb5836de9009aad483043f7 Mon Sep 17 00:00:00 2001 From: Duck McSouls Date: Sun, 25 Sep 2022 22:03:03 +1000 Subject: [PATCH 2/4] DOC: full stop for complete sentences Items in most lists look and feel like complete sentences. Insert a period for each complete sentence. --- doc/CONTRIBUTING.md | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index c3498b55c..066fabb64 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -33,16 +33,16 @@ already been reported as an [Issue](https://github.com/danielyxie/bitburner/issu #### How to Submit a Good Bug Report -- **Use a clear and descriptive title** for the issue -- **State your browser, your browser's version, and your computer's OS** -- **Attach your save file**, if you think it would help solve the issue +- **Use a clear and descriptive title** for the issue. +- **State your browser, your browser's version, and your computer's OS.** +- **Attach your save file**, if you think it would help solve the issue. - **Provide instructions on how to reproduce the bug** in as much detail as possible. If you cannot reliably reproduce the bug, then just try - your best to explain what was happening when the bug occurred -- **Provide any scripts** that triggered the bug if the issue is Netscript-related + your best to explain what was happening when the bug occurred. +- **Provide any scripts** that triggered the bug if the issue is Netscript-related. - **Open your browser's Dev Console and report any error-related output** that may be printed there. The Dev Console can be opened on most modern - browsers by pressing F12 + browsers by pressing F12. ## As a Developer @@ -110,10 +110,10 @@ Fork and clone the repo ## Development Workflow Best Practices -- Work in a new branch forked from the `dev` branch to isolate your new code +- Work in a new branch forked from the `dev` branch to isolate your new code. - Keep code-changes on a branch as small as possible. This makes it easier for code review. Each branch should be its own independent feature. - Regularly rebase your branch against `dev` to make sure you have the latest updates pulled. - - When merging, always merge your branch into `dev`. When releasing a new update, then merge `dev` into `master` + - When merging, always merge your branch into `dev`. When releasing a new update, then merge `dev` into `master`. ## Running locally. @@ -132,19 +132,19 @@ Saving a file will reload the game automatically. ### How to build the electron app -Tested on Node v16.13.1 (LTS) on Windows +Tested on Node v16.13.1 (LTS) on Windows. These steps only work in a bash-like environment, like MinGW for Windows. ```sh -# Install the main game dependencies & build the app in debug mode +# Install the main game dependencies & build the app in debug mode. npm install npm run build:dev -# Use electron-packager to build the app to the .build/ folder +# Use electron-packager to build the app to the .build/ folder. npm run electron -# When launching the .exe directly, you'll need the steam_appid.txt file in the root -# If not using windows, change this line accordingly +# When launching the .exe directly, you'll need the steam_appid.txt file in the root. +# If not using windows, change this line accordingly. cp .build/bitburner-win32-x64/resources/app/steam_appid.txt .build/bitburner-win32-x64/steam_appid.txt # And run the game... @@ -156,15 +156,15 @@ cp .build/bitburner-win32-x64/resources/app/steam_appid.txt .build/bitburner-win When submitting a pull request with your code contributions, please abide by the following rules: -- Work in a branch forked from `dev` to isolate the new code +- Work in a branch forked from `dev` to isolate the new code. - Ensure you have latest from the [game's main - repository](../../../tree/dev) -- Rebase your branch if necessary -- Run the game locally to test out your changes + repository](../../../tree/dev). +- Rebase your branch if necessary. +- Run the game locally to test out your changes. - When submitting the pull request, make sure that the base fork is _danielyxie/bitburner_ and the base is _dev_. - If your changes affect the game's UI, attach some screenshots or GIFs showing - the changes to the UI + the changes to the UI. - If your changes affect Netscript, provide some scripts that can be used to test the Netscript changes. - Ensure you have run `npm run lint` to make sure your changes conform to the @@ -187,10 +187,10 @@ We are using [API Extractor](https://api-extractor.com/pages/tsdoc/doc_comment_s Before submitting your code for a pull request, please try to follow these rules: -- Work in a branch forked from `dev` to isolate the new code +- Work in a branch forked from `dev` to isolate the new code. - Ensure you have latest from the [game's main - repository](../../../tree/dev) -- Rebase your branch if necessary + repository](../../../tree/dev). +- Rebase your branch if necessary. - When submitting the pull request, make sure that the base fork is _danielyxie/bitburner_ and the base is _dev_. - Do not check in any generated files under `doc\`. The documentation is built From 9428d5e04b58e0d8147e9d430e7712c020eefebc Mon Sep 17 00:00:00 2001 From: Duck McSouls Date: Mon, 26 Sep 2022 09:50:31 +1000 Subject: [PATCH 3/4] DOC: typo fixes in contributor's guide A bunch of typographical fixes in the guide to contribution. Ensure the presentation is consistent throughout the guide. --- doc/CONTRIBUTING.md | 56 +++++++++++++++++++++++---------------------- 1 file changed, 29 insertions(+), 27 deletions(-) diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index 066fabb64..413522452 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -3,22 +3,22 @@ ## In General The game is made better because the community as a whole speaks up about -ways to improve the game. Here's some of the ways you can make your voice +ways to improve the game. Here are some of the ways you can make your voice heard: -- [Discord](https://discord.gg/XKEGvHqVr3) +- [Discord](https://discord.gg/XKEGvHqVr3). There is a dedicated Discord instance set up for more free-form chats between all members of the community. Regular players, heavy scripters, Bitburner contributors, and everyone in between can be found on the server. -- [Github Issues](https://github.com/danielyxie/bitburner/issues) +- [Github Issues](https://github.com/danielyxie/bitburner/issues). Although the term "issues" can have a negative connotation, they are a - means of communicating with the community. A new Issue can be a + means of communicating with the community. A new Issue can be an interesting new feature that you feel would improve the game. It could be an unexpected behavior within the game. Or because the game is about scripting perhaps there is something that is conflicting with the - browser's Javascript interaction. So please do not be afraid to open a - [new issue](https://github.com/danielyxie/bitburner/issues/new). + browser's JavaScript interaction. So please do not be afraid to open a + [new Issue](https://github.com/danielyxie/bitburner/issues/new). ## Reporting Bugs @@ -33,13 +33,14 @@ already been reported as an [Issue](https://github.com/danielyxie/bitburner/issu #### How to Submit a Good Bug Report -- **Use a clear and descriptive title** for the issue. +- **Use a clear and descriptive title** for the Issue. - **State your browser, your browser's version, and your computer's OS.** -- **Attach your save file**, if you think it would help solve the issue. +- **Attach your save file**, if you think it would help solve the Issue. + Zip your save file first, then attach the zipped save file. - **Provide instructions on how to reproduce the bug** in as much detail as possible. If you cannot reliably reproduce the bug, then just try your best to explain what was happening when the bug occurred. -- **Provide any scripts** that triggered the bug if the issue is Netscript-related. +- **Provide any scripts** that triggered the bug if the Issue is Netscript-related. - **Open your browser's Dev Console and report any error-related output** that may be printed there. The Dev Console can be opened on most modern browsers by pressing F12. @@ -71,13 +72,13 @@ changes are okay to contribute: ##### Contributions that Will Most Likely Be Accepted -- Bug Fixes -- Quality-of-Life Changes +- Bug fixes +- Quality-of-life changes - Adding a new, commonly-requested Netscript function - Fixing or improving UI elements - Adding game settings/options - Adding a new Terminal command -- Code Refactors that conform to good/standard practices +- Code refactors that conform to good/standard practices ##### Contributions that will not be Accepted without prior approval @@ -113,19 +114,20 @@ Fork and clone the repo - Work in a new branch forked from the `dev` branch to isolate your new code. - Keep code-changes on a branch as small as possible. This makes it easier for code review. Each branch should be its own independent feature. - Regularly rebase your branch against `dev` to make sure you have the latest updates pulled. - - When merging, always merge your branch into `dev`. When releasing a new update, then merge `dev` into `master`. + - When merging, always merge your branch into `dev`. When releasing a new update, merge `dev` into `master`. -## Running locally. +## Running locally Install - `npm` (maybe via `nvm`) -- Github Desktop (windows only) -- Visual Studio code (optional) +- Github Desktop (Windows only) +- Visual Studio Code (optional) -Inside the root of the repo run -`npm install` to install all the dependencies -`npm run start:dev` to launch the game in dev mode. +Inside the root of the repository run: + +- `npm install` to install all the dependencies; and +- `npm run start:dev` to launch the game in dev mode. After that you can open any browser and navigate to `localhost:8000` and play the game. Saving a file will reload the game automatically. @@ -133,7 +135,7 @@ Saving a file will reload the game automatically. ### How to build the electron app Tested on Node v16.13.1 (LTS) on Windows. -These steps only work in a bash-like environment, like MinGW for Windows. +These steps only work in a Bash-like environment, like MinGW for Windows. ```sh # Install the main game dependencies & build the app in debug mode. @@ -144,7 +146,7 @@ npm run build:dev npm run electron # When launching the .exe directly, you'll need the steam_appid.txt file in the root. -# If not using windows, change this line accordingly. +# If not using Windows, change this line accordingly. cp .build/bitburner-win32-x64/resources/app/steam_appid.txt .build/bitburner-win32-x64/steam_appid.txt # And run the game... @@ -157,7 +159,7 @@ When submitting a pull request with your code contributions, please abide by the following rules: - Work in a branch forked from `dev` to isolate the new code. -- Ensure you have latest from the [game's main +- Ensure you have the latest from the [game's main repository](../../../tree/dev). - Rebase your branch if necessary. - Run the game locally to test out your changes. @@ -174,21 +176,21 @@ the following rules: in the root of the repository. These will be updated as part of official releases. -## As a Documentor +## As a Documenter To contribute to and view your changes to the BitBurner documentation on [Read The Docs](http://bitburner.readthedocs.io/), you will need to have Python installed, along with [Sphinx](http://www.sphinx-doc.org). -To make change to the [in-game documentation](../markdown/bitburner.md), you will need to modify the [TypeScript definitions](../src/ScriptEditor/NetscriptDefinitions.d.ts), not the markdown files. +To make change to the [in-game documentation](../markdown/bitburner.md), you will need to modify the [TypeScript definitions](../src/ScriptEditor/NetscriptDefinitions.d.ts), not the Markdown files. -We are using [API Extractor](https://api-extractor.com/pages/tsdoc/doc_comment_syntax/) (tsdoc hints) to generate the markdown doc. Make your changes to the TypeScript definitions and then run `npm run doc`. +We are using [API Extractor](https://api-extractor.com/pages/tsdoc/doc_comment_syntax/) (tsdoc hints) to generate the Markdown doc. Make your changes to the TypeScript definitions and then run `npm run doc`. Before submitting your code for a pull request, please try to follow these rules: - Work in a branch forked from `dev` to isolate the new code. -- Ensure you have latest from the [game's main +- Ensure you have the latest from the [game's main repository](../../../tree/dev). - Rebase your branch if necessary. - When submitting the pull request, make sure that the base fork is @@ -204,5 +206,5 @@ Update the following - `package.json` `version` - `doc/source/conf.py` `version` and `release` - `doc/source/changelog.rst` -- post to discord +- post to Discord - post to reddit.com/r/Bitburner From c90696c9672304ce24019f604383c94f7c35494d Mon Sep 17 00:00:00 2001 From: Duck McSouls Date: Mon, 26 Sep 2022 09:51:38 +1000 Subject: [PATCH 4/4] DOC: how to fork and clone; consistent shell presentation Add to the contributor's guide various ways to clone and fork the code repository. These methods are: (1) web browser; (2) GitHub Desktop; and (3) command line. Be consistent in how shell commands are presented. --- doc/CONTRIBUTING.md | 78 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 59 insertions(+), 19 deletions(-) diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index 413522452..08e4a9bce 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -89,24 +89,64 @@ changes are okay to contribute: ## How to setup fork properly -Fork and clone the repo +Clone and fork the game's repository by using one of these methods: web browser, GitHub +Desktop, or command line. -``` - # This will add the game original code as a repo in your local copy - $ git remote add danielyxie git@github.com:danielyxie/bitburner.git +- Web browser. Log in to your GitHub account, navigate to the + [game's repository](https://github.com/danielyxie/bitburner), and fork the + repository. Refer to + [this page](https://docs.github.com/en/get-started/quickstart/fork-a-repo) for more + detail. +- GitHub Desktop. Click on `File`, then click `Clone repository`. Click on the `URL` + tab and type `danielyxie/bitburner` into the text box for repository URL. Choose + the path where you want to clone the repository and click the `Clone` button. + Refer to [this page](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/adding-and-cloning-repositories/cloning-and-forking-repositories-from-github-desktop) + for more detail. +- Command line. - # You can verify you did this right by doing the following command - $ git remote show - danielyxie - origin +```sh +# This clones the game's code repository. The output you get might vary. +$ git clone https://github.com/danielyxie/bitburner.git +Cloning into 'bitburner'... +remote: Enumerating objects: 57072, done. +remote: Counting objects: 100% (404/404), done. +remote: Compressing objects: 100% (205/205), done. +remote: Total 57072 (delta 210), reused 375 (delta 199), pack-reused 56668 +Receiving objects: 100% (57072/57072), 339.11 MiB | 5.42 MiB/s, done. +Resolving deltas: 100% (43708/43708), done. +Updating files: 100% (2561/2561), done. - # Then download all the branches from the game. (there might be more branches) - $ git fetch danielyxie - From github.com:danielyxie/bitburner - * [new branch] dev -> danielyxie/dev - * [new branch] master -> danielyxie/master +# Change to the directory that contains your local copy. +$ cd bitburner - # Makes sure you always start from `danielyxie/dev` to avoid merge conflicts. +# The upstream is the repository that contains the game's source code. The +# upstream is also the place where proposed changes are merged into the game. +$ git remote rename origin upstream +Renaming remote references: 100% (8/8), done. + +# The origin is your own copy or fork of the game's source code. Assume that +# your fork will be on GitHub. Change "myname" to your GitHub username. Change +# "myfork" to the name of your forked repository. +$ git remote add origin https://github.com/myname/myfork + +# Now "origin" is your fork and "upstream" is where changes should be merged. +$ git remote show +origin +upstream + +# You can now download all changes and branches from the upstream repository. +# The output you get might vary. +$ git fetch upstream + +# Make sure you always start from "upstream/dev" to avoid merge conflicts. +$ git branch +* dev +$ git branch -r +upstream/BN14 +upstream/HEAD -> upstream/dev +upstream/dev +upstream/folders +upstream/master ``` ## Development Workflow Best Practices @@ -139,18 +179,18 @@ These steps only work in a Bash-like environment, like MinGW for Windows. ```sh # Install the main game dependencies & build the app in debug mode. -npm install -npm run build:dev +$ npm install +$ npm run build:dev # Use electron-packager to build the app to the .build/ folder. -npm run electron +$ npm run electron # When launching the .exe directly, you'll need the steam_appid.txt file in the root. # If not using Windows, change this line accordingly. -cp .build/bitburner-win32-x64/resources/app/steam_appid.txt .build/bitburner-win32-x64/steam_appid.txt +$ cp .build/bitburner-win32-x64/resources/app/steam_appid.txt .build/bitburner-win32-x64/steam_appid.txt # And run the game... -.build/bitburner-win32-x64/bitburner.exe +$ .build/bitburner-win32-x64/bitburner.exe ``` ### Submitting a Pull Request