docs: add prerequisites and other documentation tweaks (#6)

* docs: add prerequisites and other documentation tweaks

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 ## Local Testing
 
-1. Install dependancies
+1. Install dependencies
 
    ```zsh
    yarn install

README.md

@@ -1,5 +1,22 @@
 # [Backstage w/ Autogov plugin](https://backstage.io)
 
+## Prerequisites
+
+You will need [Node v20 installed](https://nodejs.org/en/download/package-manager) on your machine.
+
+You will need [yarn v4 installed](https://yarnpkg.com/getting-started/install) on your machine.
+
+> **Note**: Make sure you have the correct versions of Node and Yarn installed. Using incorrect versions may lead to unexpected issues.
+
+## Initial Setup
+
+Before proceeding, verify your development environment:
+
+```sh
+node --version  # Should show v20.x.x
+yarn --version  # Should show v4.x.x
+```
+
 ## Setup GitHub
 
 To use the Github APIs, a basic Github Auth token is required. It does not need access to any specific repositories, just basic read-access to public repositories.
@@ -8,161 +25,86 @@ To use the Github APIs, a basic Github Auth token is required. It does not need
 
 #### GitHub Token
 
-1. create a .env
-1. create GITHUB_TOKEN and add to .env (for [retrieving release assets](https://docs.github.com/en/rest/releases/assets?apiVersion=2022-11-28#get-a-release-asset))
+1. Go to GitHub Settings > Developer Settings > Personal Access Tokens
+2. Create a new token with "Contents" repository permissions (read)
+3. Create a `.env` file in the root directory
+4. Add your token as `GITHUB_TOKEN=your_token_here`
 
-  ```md
-  For GITHUB_TOKEN:
-  Fine-grained access tokens for "Get a release asset"
+```md
+For GITHUB_TOKEN:
+Fine-grained access tokens for "Get a release asset"
 
-  This endpoint works with the following fine-grained token types:
+This endpoint works with the following fine-grained token types:
 
-  GitHub App user access tokens
-  GitHub App installation access tokens
-  Fine-grained personal access tokens
-  The fine-grained token must have the following permission set:
+GitHub App user access tokens
+GitHub App installation access tokens
+Fine-grained personal access tokens
+The fine-grained token must have the following permission set:
 
-  "Contents" repository permissions (read)
-  ```
+"Contents" repository permissions (read)
+```
 
 ## Run the App
 
-1. To start the app, run:
+1. Install dependencies:
 
-  ```sh
-  yarn install
-  yarn dev
-  ```
+   ```sh
+   yarn install
+   ```
 
-## Autogov Plugins
-
-The following outlines what changes were made to a new Backstage instance to enable the Autogov Plugins. These changes are already done in this repo. The changes listed here are for informational purposes.
+1. Start the application:
 
-### enable dotenv
+   ```sh
+   yarn dev
+   ```
 
-```package.json
-"scripts": {
-    "dev": "concurrently \"yarn start\" \"yarn start-backend\"",
-    "start": "dotenv -e .env yarn workspace app start",
-    "start-backend": "dotenv -e .env yarn workspace backend start",
-```
+> **Note**: The application runs on `http://localhost:3000` by default. You should see the Backstage interface once it's running.
 
-1. add dependencies:
+## Troubleshooting
 
-  ```zsh
-  yarn add concurrently
-  yarn add dotenv
-  yarn add dotenv-cli
-  ```
+Common issues and solutions:
 
-### Add Autogov Plugins
+- If `yarn install` fails, try clearing your yarn cache: `yarn cache clean`
+- If the app doesn't start, check if all required environment variables are set in `.env`
+- For plugin-related issues, ensure all plugin dependencies are correctly installed
 
-1. To install to the Autogov Plugins to the appropriate place, run the following two commands:
+## Autogov Plugins
 
-    ```zsh
-    # from root
-    yarn --cwd packages/app add @liatrio/backstage-plugin-autogov-releases-card@^1.6.2 @liatrio/backstage-plugin-autogov-status-catalog-column@^1.6.2
-    yarn --cwd packages/backend add @liatrio/backstage-plugin-autogov-releases-backend@^1.6.2 @liatrio/backstage-plugin-backend-module-autogov-processor@^1.6.2
-    ```
+The following outlines what changes were made to a new Backstage instance to enable the Autogov Plugins. These changes are already done in this repo. The changes listed here are for informational purposes.
 
-#### Autogov Plug-in Release Card Backend
+### Enable dotenv
 
-1. Update `packages/backend/src/index.ts` with:
+1. Modify the following scripts in the `package.json` file:
 
-  ```diff
-  +  backend.add(
-  +    import('@liatrio/backstage-plugin-autogov-releases-backend'),
-  +  );
-  backend.start();
-  ```
+   ```json
+   "scripts": {
+     "dev": "concurrently \"yarn start\" \"yarn start-backend\"",
+     "start": "dotenv -e .env yarn workspace app start",
+     "start-backend": "dotenv -e .env yarn workspace backend start",
+   ```
 
-#### Autogov Plug-in Release Card Frontend
-
-1. Update `packages/app/src/components/catalog/EntityPage.tsx` with:
-
-    ```diff
-    + import { AutogovReleasesCard } from '@liatrio/backstage-plugin-autogov-releases-card';
-    ```
-
-1. Further down, find the following block of code:
-
-    ```diff
-    const overviewContent = (
-      <Grid container spacing={3} alignItems="stretch">
-        {entityWarningContent}
-        <Grid item md={6}>
-          <EntityAboutCard variant="gridItem" />
-        </Grid>
-        <Grid item md={6} xs={12}>
-          <EntityCatalogGraphCard variant="gridItem" height={400} />
-        </Grid>
-
-        <Grid item md={4} xs={12}>
-          <EntityLinksCard />
-        </Grid>
-        <Grid item md={8} xs={12}>
-          <EntityHasSubcomponentsCard variant="gridItem" />
-        </Grid>
-    +    <EntitySwitch>
-    +      <EntitySwitch.Case
-    +        if={isKind('component') && isComponentType(['website', 'service'])}
-    +      >
-    +        <Grid item md={8} xs={12}>
-    +          <AutogovReleasesCard />
-    +        </Grid>
-    +      </EntitySwitch.Case>
-    +    </EntitySwitch>
-      </Grid>
-    );
-    ```
-
-#### Autogov Plug-in Latest Release Autogov Status Catalog Processor
-
-1. Update `packages/backend/src/index.ts` with:
-
-  ```diff
-  +  backend.add(
-  +    import('@liatrio/backstage-plugin-backend-module-autogov-processor'),
-  +  );
-  backend.start();
-  ```
+1. add dependencies:
 
-#### Autogov Plug-in Latest Release Autogov Status Catalog Column
+   ```bash
+   yarn add concurrently
+   yarn add dotenv
+   yarn add dotenv-cli
+   ```
 
-1. Update `packages/app/App.tsx`:
+### Add Autogov Plugins
 
-  ```diff
-  +  import {
-  +    defaultColumnsWithAutogovStatusRightOf,
-  +    AutogovLatestReleaseStatusPicker,
-  +  } from '@liatrio/backstage-plugin-autogov-status-catalog-column';
-  +  import { DefaultFilters } from '@backstage/plugin-catalog-react';
+- To install to the Autogov Plugins to the appropriate place, run the following two commands:
 
-  const app = createApp({
+  ```zsh
+  # from root
+  yarn --cwd packages/app add @liatrio/backstage-plugin-autogov-releases-card@^1.6.2 @liatrio/backstage-plugin-autogov-status-catalog-column@^1.6.2
+  yarn --cwd packages/backend add @liatrio/backstage-plugin-autogov-releases-backend@^1.6.2 @liatrio/backstage-plugin-backend-module-autogov-processor@^1.6.2
   ```
 
-1. Further down, find the following code block and update:
-
-```diff
--      <Route path="/catalog" element={<CatalogIndexPage />} />
-+      <Route
-+        path="/catalog"
-+        element={
-+          <CatalogIndexPage
-+            columns={context =>
-+              defaultColumnsWithAutogovStatusRightOf('Description', context)
-+            }
-+            filters={
-+              <>
-+                <DefaultFilters />
-+                <AutogovLatestReleaseStatusPicker />
-+              </>
-+            }
-+          />
-+        }
-+      />
-```
+> **Note**: After installing plugins, you may need to restart your development server for changes to take effect.
 
 ## Contributing
 
 See [Contributing](./CONTRIBUTING) to Backstage GitHub Releases Autogov Plugin
+
+> **Note**: First time contributors should review the Contributing guide carefully before submitting any changes.

app-config.yaml

@@ -147,4 +147,4 @@ autogov:
     entityTypes:
       - website
       - service
-    maxReleases: 5
+    maxReleases: {}

kubecon-backstagecon-2024.md

@@ -10,4 +10,4 @@ Links:
 - [Session Survey](https://app.formbricks.com/s/cm2uq8cv500007edyy1bq4xku)
 - Speakers:
   - [Amber Beasley](https://www.linkedin.com/in/amber-beasley-a9278565/)
-  - [Daniel Hagen](https://www.linkedin.com/in/daniel-b-hagen/)
+  - [Daniel Hagen](https://www.linkedin.com/in/daniel-b-hagen/)

package.json

@@ -22,6 +22,7 @@
     "lint": "backstage-cli repo lint --since origin/main",
     "lint:all": "backstage-cli repo lint",
     "prettier:check": "prettier --check .",
+    "prettier:fix": "prettier --write .",
     "new": "backstage-cli new --scope internal"
   },
   "workspaces": {

packages/app/package.json

@@ -43,7 +43,6 @@
     "@liatrio/backstage-plugin-autogov-status-catalog-column": "1.6.2",
     "@material-ui/core": "^4.12.2",
     "@material-ui/icons": "^4.9.1",
-    "@roadiehq/backstage-plugin-github-insights": "^2.4.3",
     "history": "^5.0.0",
     "react": "^18.0.2",
     "react-dom": "^18.0.2",