From 75ee6f8b16732929c941461b3f80cb1c6f2be198 Mon Sep 17 00:00:00 2001 From: Resi Respati Date: Sat, 2 Dec 2017 00:57:07 +0700 Subject: [PATCH] Finalise docs Notes: * Will fill in the 'What's new' section after @arcath is finished with his article draft * Will add the legacy branch link when it's available --- CONTRIBUTING.md | 39 ++++++++++++++++++++++++++++++++ docs/README.md | 2 +- docs/SUMMARY.md | 4 ++-- docs/contributing.md | 39 ++++++++++++++++++++++++++++++++ docs/faq-troubleshooting.md | 5 ---- docs/in-depth/module-bundling.md | 2 -- docs/in-depth/typescript.md | 9 +++++++- docs/troubleshooting.md | 13 +++++++++++ 8 files changed, 102 insertions(+), 11 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 docs/contributing.md delete mode 100644 docs/faq-troubleshooting.md create mode 100644 docs/troubleshooting.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4a24148 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,39 @@ +# Contributing guidelines + +This document outlines guides to get started on developing the starter kit. + +## Contributing to the docs + +We welcome contributions to the docs! We're looking for ways to make the starter kit documentation better, as well as many other tips and tricks about Screeps AI development in TypeScript. + +You can start working on the docs locally as well. First, you'll need to install the [Gitbook](https://www.gitbook.com/) CLI. + +```bash +npm install -g gitbook-cli +``` + +To run a local Gitbook server, run the following command on the project's root directory. + +```bash +gitbook serve +``` + +## The Five Golden Rules + +The simple steps of contributing to any GitHub project are as follows: + +1. [Fork the repository](https://github.com/screepers/screeps-typescript-starter/fork) +2. Create your feature branch: `git checkout -b my-new-feature` +3. Commit your changes: `git commit -am 'Add some feature'` +4. Push to the branch: `git push -u origin my-new-feature` +5. Create a [Pull Request](https://github.com/screepers/screeps-typescript-starter/pulls)! + +To keep your fork of in sync with this repository, [follow this guide](https://help.github.com/articles/syncing-a-fork/). + +## Submitting a Pull Request + +We accept almost all pull requests, as long as the following criterias are met: + +* Your code must pass all of the linter checks (`npm run lint`) +* When adding a new feature, make sure it doesn't increase the complexity of the tooling. We want this starter kit to be approachable to folks who have little to no knowledge of TypeScript, or even JavaScript. +* When making changes that are potentially breaking, careful discussion must be done with the community at large. Generally we do this either on the [#typescript](https://screeps.slack.com/messages/typecript/) channel on the Screeps Slack, or on the corresponding pull request discussion thread. diff --git a/docs/README.md b/docs/README.md index 8612157..ced7806 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,7 +2,7 @@ Screeps Typescript Starter is a starting point for a Screeps AI written in Typescript. It provides everything you need to start writing your AI whilst leaving `main.ts` as empty as possible. -## What's New +## What's new [TODO] diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 94920db..0ac36a9 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -15,8 +15,8 @@ * [Deploy destinations](./in-depth/deploy-destinations.md) * [TypeScript](./in-depth/typescript.md) * [Cookbook](./in-depth/cookbook.md) - * [TODO] --- -* [FAQ & Troubleshooting](./faq-troubleshooting.md) +* [Troubleshooting](./troubleshooting.md) +* [Contributing guidelines](./contributing.md) diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..4a24148 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,39 @@ +# Contributing guidelines + +This document outlines guides to get started on developing the starter kit. + +## Contributing to the docs + +We welcome contributions to the docs! We're looking for ways to make the starter kit documentation better, as well as many other tips and tricks about Screeps AI development in TypeScript. + +You can start working on the docs locally as well. First, you'll need to install the [Gitbook](https://www.gitbook.com/) CLI. + +```bash +npm install -g gitbook-cli +``` + +To run a local Gitbook server, run the following command on the project's root directory. + +```bash +gitbook serve +``` + +## The Five Golden Rules + +The simple steps of contributing to any GitHub project are as follows: + +1. [Fork the repository](https://github.com/screepers/screeps-typescript-starter/fork) +2. Create your feature branch: `git checkout -b my-new-feature` +3. Commit your changes: `git commit -am 'Add some feature'` +4. Push to the branch: `git push -u origin my-new-feature` +5. Create a [Pull Request](https://github.com/screepers/screeps-typescript-starter/pulls)! + +To keep your fork of in sync with this repository, [follow this guide](https://help.github.com/articles/syncing-a-fork/). + +## Submitting a Pull Request + +We accept almost all pull requests, as long as the following criterias are met: + +* Your code must pass all of the linter checks (`npm run lint`) +* When adding a new feature, make sure it doesn't increase the complexity of the tooling. We want this starter kit to be approachable to folks who have little to no knowledge of TypeScript, or even JavaScript. +* When making changes that are potentially breaking, careful discussion must be done with the community at large. Generally we do this either on the [#typescript](https://screeps.slack.com/messages/typecript/) channel on the Screeps Slack, or on the corresponding pull request discussion thread. diff --git a/docs/faq-troubleshooting.md b/docs/faq-troubleshooting.md deleted file mode 100644 index 84e26fd..0000000 --- a/docs/faq-troubleshooting.md +++ /dev/null @@ -1,5 +0,0 @@ -# FAQ & Troubleshooting - -This page outlines any common issues that you'll run into while setting up the TypeScript starter, as well as how to fix them. - -[TODO] diff --git a/docs/in-depth/module-bundling.md b/docs/in-depth/module-bundling.md index bbce3c3..bbab63d 100644 --- a/docs/in-depth/module-bundling.md +++ b/docs/in-depth/module-bundling.md @@ -12,8 +12,6 @@ Then you can import these libraries just like you would any other `npm` module. Some module bundlers even support performing further optimisations like eliminating unused module functions from your final bundled code (aka. _tree-shaking_), reducing the size of your final bundled JS even further. -[TODO: more advantages of bundling code, if any] - ## Rollup From version 3.0 onwards, the starter kit uses Rollup as its main module bundler. Some useful features of Rollup include: diff --git a/docs/in-depth/typescript.md b/docs/in-depth/typescript.md index 53eca71..9583ddc 100644 --- a/docs/in-depth/typescript.md +++ b/docs/in-depth/typescript.md @@ -22,7 +22,14 @@ Starting from version 2.0 of the starter kit, we've enabled the `--strict` flag TSLint checks your TypeScript code for readability, maintainability, and functionality errors, and can also enforce coding style standards. -[TODO: describe TSlint rules used in brief] +This project provides TSLint rules through a `tslint.json` file, which extends the recommended rules from TSLint defined [here](https://github.com/palantir/tslint/blob/next/src/configs/recommended.ts). + +We've made some changes to these rules, which we considered necessary and/or relevant to a proper Screeps project: + + - set the [forin](http://palantir.github.io/tslint/rules/forin/) rule to `false`, it was forcing `for ( ... in ...)` loops to check if object members were not coming from the class prototype. + - set the [interface-name](http://palantir.github.io/tslint/rules/interface-name/) rule to `false`, in order to allow interfaces that are not prefixed with `I`. + - set the [no-console](http://palantir.github.io/tslint/rules/no-console/) rule to `false`, in order to allow using `console`. + - in the [variable-name](http://palantir.github.io/tslint/rules/variable-name/) rule, added `allow-leading-underscore`. ### Customising TSLint diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..828548b --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,13 @@ +# Troubleshooting + +This page outlines any common issues that you'll run into while setting up the TypeScript starter, as well as how to fix them. + +## Unable to upload code to Screeps private server + +If you're getting the following error: + +``` +(node:80116) UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1): Error: Cannot POST /api/auth/signin +``` + +Make sure you have [screepsmod-auth](https://github.com/ScreepsMods/screepsmod-auth) installed on your private server, and you've set a password on the account in your private server as well.