Merge pull request #4518 from backstage/blam/docs-restructure

Rework some of the getting started Docs

CONTRIBUTING.md

@@ -66,7 +66,7 @@ Have you started using Backstage? Adding your company to [ADOPTERS](ADOPTERS.md)
 
 So...feel ready to jump in? Let's do this. 👏🏻💯
 
-Start by reading our [Getting Started](https://backstage.io/docs/getting-started/) page. If you need help, just jump into our [Discord chatroom](https://discord.gg/MUpMjP2).
+Start by reading our [Getting Started for Contributors](https://backstage.io/docs/getting-started/contributors) page to get yourself setup with a fresh copy of Backstage ready for your contributions. If you need help, just jump into our [Discord chatroom](https://discord.gg/MUpMjP2).
 
 ## Coding Guidelines
 

docs/getting-started/contributors.md

@@ -1,6 +1,6 @@
 ---
-id: development-environment
-title: Development Environment
+id: contributors
+title: Contributors
 # prettier-ignore
 description: Documentation on how to get set up for doing development on the Backstage repository
 ---
@@ -10,6 +10,21 @@ repository.
 
 ## Cloning the Repository
 
+Ok. So you're gonna want some code right? Go ahead and fork the repository into
+your own GitHub account and clone that code to your local machine or you can
+grab the one for the origin like so:
+
+```bash
+git clone git@github.com/backstage/backstage --depth 1
+```
+
+If you cloned a fork, you can add the upstream dependency like so:
+
+```bash
+git remote add upstream git@github.com:backstage/backstage
+git pull upstream master
+```
+
 After you have cloned the Backstage repository, you should run the following
 commands once to set things up for development:
 
@@ -25,9 +40,11 @@ Open a terminal window and start the web app by using the following command from
 the project root. Make sure you have run the above mentioned commands first.
 
 ```bash
-$ yarn start
+$ yarn dev
 ```
 
+This is going to start two things, the frontend (:3000) and the backend (:7000).
+
 This should open a local instance of Backstage in your browser, otherwise open
 one of the URLs printed in the terminal.
 
@@ -38,12 +55,27 @@ setting an environment variable `PORT` on your local machine. e.g.
 Once successfully started, you should see the following message in your terminal
 window:
 
+```sh
+$ concurrently "yarn start" "yarn start-backend"
+$ yarn workspace example-app start
+$ yarn workspace example-backend start
+$ backstage-cli app:serve
+$ backstage-cli backend:dev
+[0] Loaded config from app-config.yaml
+[1] Build succeeded
+[0] ℹ ｢wds｣: Project is running at http://localhost:3000/
+[0] ℹ ｢wds｣: webpack output is served from /
+[0] ℹ ｢wds｣: Content not from webpack is served from $BACKSTAGE_DIR/packages/app/public
+[0] ℹ ｢wds｣: 404s will fallback to /index.html
+[0] ℹ ｢wdm｣: wait until bundle finished: /
+[1] 2021-02-12T20:58:17.614Z backstage info Loaded config from app-config.yaml
 ```
-You can now view example-app in the browser.
 
-  Local:            http://localhost:8080
-  On Your Network:  http://192.168.1.224:8080
-```
+You'll see how you get both logs for the frontend `webpack-dev-server` which
+serves the react app ([0]) and the backend ([1]);
+
+Visit http://localhost:3000 and you should see the bleeding edge of Backstage
+ready for contributions!
 
 ## Editor
 

docs/getting-started/create-an-app.md

@@ -177,20 +177,6 @@ the root directory:
 yarn workspace backend start
 ```
 
+Now you're free to hack away on your own Backstage installation!
+
 ### Troubleshooting
-
-#### Cannot find module
-
-You may encounter an error similar to below:
-
-```
-internal/modules/cjs/loader.js:968
-  throw err;
-  ^
-
-Error: Cannot find module '../build/Debug/nodegit.node'
-```
-
-This can occur if an npm dependency is not completely installed. Because some
-dependencies run a post-install script, ensure that both your npm and yarn
-configs have the `ignore-scripts` flag set to `false`.

docs/getting-started/index.md

@@ -19,7 +19,7 @@ general, it's easier to fork and clone this project. That will let you stay up
 to date with the latest changes, and gives you an easier path to make Pull
 Requests towards this repo.
 
-### Creating a Standalone App
+### Create your Backstage App
 
 Backstage provides the `@backstage/create-app` package to scaffold standalone
 instances of Backstage. You will need to have
@@ -46,8 +46,3 @@ look something like this. You can read more about this process in
 You can read more in our
 [CONTRIBUTING](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md)
 guide, which can help you get setup with a Backstage development environment.
-
-### Next steps
-
-Take a look at the [Running Backstage Locally](./running-backstage-locally.md)
-guide to learn how to set up Backstage, and how to develop on the platform.

docs/getting-started/running-backstage-locally.md

@@ -104,7 +104,6 @@ The value of Backstage grows with every new plugin that gets added. Here is a
 collection of tutorials that will guide you through setting up and extending an
 instance of Backstage with your own plugins.
 
-- [Development Environment](development-environment.md)
 - [Create a Backstage Plugin](../plugins/create-a-plugin.md)
 - [Structure of a Plugin](../plugins/structure-of-a-plugin.md)
 - [Utility APIs](../api/utility-apis.md)

microsite/sidebars.json

@@ -13,7 +13,7 @@
     "Getting Started": [
       "getting-started/index",
       "getting-started/running-backstage-locally",
-      "getting-started/development-environment",
+      "getting-started/contributing",
       "getting-started/create-an-app",
       {
         "type": "subcategory",

mkdocs.yml

@@ -16,7 +16,7 @@ nav:
   - Getting started:
       - Getting Started: 'getting-started/index.md'
       - Running Backstage locally: 'getting-started/running-backstage-locally.md'
-      - Local development: 'getting-started/development-environment.md'
+      - Contributors: 'getting-started/contributors.md'
       - Demo deployment: https://backstage-demo.roadie.io
       - Production deployments:
           - Create an App: 'getting-started/create-an-app.md'