From cbf4566ed619f5e19707a7ee3e9b18bfcbaaa4de Mon Sep 17 00:00:00 2001 From: blam Date: Fri, 12 Feb 2021 23:31:55 +0100 Subject: [PATCH 1/3] docs: rework the getting started documentation for both contributors and integraters are seperated --- CONTRIBUTING.md | 2 +- .../development-environment.md | 30 +++++++++++++++---- docs/getting-started/index.md | 7 +---- 3 files changed, 27 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d163a42954..fb6b524c14 100644 --- a/CONTRIBUTING.md +++ b/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 [Development Environment](https://backstage.io/docs/getting-started/development-environment) 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 diff --git a/docs/getting-started/development-environment.md b/docs/getting-started/development-environment.md index 01fd7bdc24..cbbb2798f4 100644 --- a/docs/getting-started/development-environment.md +++ b/docs/getting-started/development-environment.md @@ -10,6 +10,9 @@ 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! + After you have cloned the Backstage repository, you should run the following commands once to set things up for development: @@ -25,9 +28,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. @@ -39,12 +44,27 @@ Once successfully started, you should see the following message in your terminal window: ``` -You can now view example-app in the browser. - - Local: http://localhost:8080 - On Your Network: http://192.168.1.224:8080 +$ 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'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 The Backstage development environment does not require any specific editor, but diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 16c837d676..b946039dfb 100644 --- a/docs/getting-started/index.md +++ b/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. From 687ddc49d7c635e183905b52536f460e4ff76a43 Mon Sep 17 00:00:00 2001 From: blam Date: Fri, 12 Feb 2021 23:50:03 +0100 Subject: [PATCH 2/3] chore: reworking the title of the docs to avoid confusion --- CONTRIBUTING.md | 2 +- .../{development-environment.md => contributors.md} | 13 +++++++++---- 2 files changed, 10 insertions(+), 5 deletions(-) rename docs/getting-started/{development-environment.md => contributors.md} (96%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fb6b524c14..ddc5449cd8 100644 --- a/CONTRIBUTING.md +++ b/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 [Development Environment](https://backstage.io/docs/getting-started/development-environment) 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). +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 diff --git a/docs/getting-started/development-environment.md b/docs/getting-started/contributors.md similarity index 96% rename from docs/getting-started/development-environment.md rename to docs/getting-started/contributors.md index cbbb2798f4..e7e1986170 100644 --- a/docs/getting-started/development-environment.md +++ b/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 --- @@ -11,7 +11,12 @@ 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! +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 +``` After you have cloned the Backstage repository, you should run the following commands once to set things up for development: @@ -43,7 +48,7 @@ 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 From d7abf2a2db57b7a38db419c0f71bfc8816ad24d0 Mon Sep 17 00:00:00 2001 From: blam Date: Tue, 16 Feb 2021 15:19:31 +0100 Subject: [PATCH 3/3] chore: fix some other wording --- docs/getting-started/contributors.md | 7 +++++++ docs/getting-started/create-an-app.md | 18 ++---------------- .../running-backstage-locally.md | 1 - microsite/sidebars.json | 2 +- mkdocs.yml | 2 +- 5 files changed, 11 insertions(+), 19 deletions(-) diff --git a/docs/getting-started/contributors.md b/docs/getting-started/contributors.md index e7e1986170..a0c3f3dc4c 100644 --- a/docs/getting-started/contributors.md +++ b/docs/getting-started/contributors.md @@ -18,6 +18,13 @@ grab the one for the origin like so: 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: diff --git a/docs/getting-started/create-an-app.md b/docs/getting-started/create-an-app.md index 0663d3faa1..9abb68d21b 100644 --- a/docs/getting-started/create-an-app.md +++ b/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`. diff --git a/docs/getting-started/running-backstage-locally.md b/docs/getting-started/running-backstage-locally.md index 6de9d234e3..fe68937c4e 100644 --- a/docs/getting-started/running-backstage-locally.md +++ b/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) diff --git a/microsite/sidebars.json b/microsite/sidebars.json index ebce8d900c..090c967ff4 100644 --- a/microsite/sidebars.json +++ b/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", diff --git a/mkdocs.yml b/mkdocs.yml index a303fd9978..37f7aa2e62 100644 --- a/mkdocs.yml +++ b/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'