updated readme, contribution guidelines, and associated docs

.github/ISSUE_TEMPLATE/bug-report.md

@@ -2,31 +2,35 @@
 name: Bug Report
 about: Create a report to help us improve.
 title: "[Bug] Your Bug Report Here"
-labels: ''
+labels: ""
-assignees: ''
+assignees: ""
-
 ---
 
-**Describe the bug**
+**Describe the bug** A clear and concise description of what the bug is.
-A clear and concise description of what the bug is.
+
+**To Reproduce** Steps to reproduce the behavior:
 
-**To Reproduce**
-Steps to reproduce the behavior:
 1. Go to '...'
 2. Click on '....'
 3. Scroll down to '....'
 4. See error
 
-**Expected behavior**
+**Expected behavior** A clear and concise description of what you expected to
-A clear and concise description of what you expected to happen.
+happen.
 
-**Screenshots**
+**Actual behavior** A clear and concise description of what actually happens.
-If applicable, add screenshots to help explain your problem.
+
+**Screenshots** If applicable, add screenshots to help explain your problem.
 
 **Operating System (please complete the following information):**
- - OS: [e.g. Windows 10 19044.1889, Ubuntu 18.04, Mac OS Monterey 12.4]
- - CLI Environment [e.g. Command Prompt, Powershell, Terminal]
- - Version [e.g. 1.04]
 
-**Additional context**
+- OS: [e.g. Windows 10 19044.1889, Ubuntu 18.04, Mac OS Monterey 12.4]
-Add any other context about the problem here.
+- CLI Environment [e.g. Command Prompt, Powershell, Terminal]
+- Version [e.g. 1.04]
+
+**Browser (please complete the following information):**
+
+- Browser: [e.g. Chrome, Firefox, Brave, Safari]
+- Version [e.g. 1.04]
+
+**Additional context** Add any other context about the problem here.

CONTRIBUTING.md

@@ -1,48 +1,108 @@
-# Contributing to Transcriptase
+# Contributing to developer.sailpoint.com
-We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:
 
-- Reporting a bug
+We love your input! We want to make contributing to this project as easy and
-- Discussing the current state of the code
+transparent as possible. Look below if you would like to:
-- Submitting a fix
+
-- Proposing new features
+- [Reporting a bug](#report-bugs-using-our-repositorys-issueshttpsgithubcomsailpoint-ossdevelopersailpointcomissues)
-- Becoming a maintainer
+- [Make a feature request](#make-a-feature-request-using-our-repositorys-issueshttpsgithubcomsailpoint-ossdevelopersailpointcomissues)
+- [Submitting a fix](#submit-a-fix)
+- [Submit a new feature](#submit-a-new-feature)
+- [Submit a general issue or ask a question](#discuss-submit-general-issue-or-ask-a-question)
+
+# High-level Guidelines
 
 ## We Develop with Github
-We use github to host code, to track issues and feature requests, as well as accept pull requests.
+
+We use github to host code, to track issues and feature requests, as well as
+accept pull requests.
 
 ## We Use [Github Flow](https://docs.github.com/en/get-started/quickstart/github-flow), So All Code Changes Happen Through Pull Requests
-Pull requests are the best way to propose changes to the codebase (we use [Github Flow](https://docs.github.com/en/get-started/quickstart/github-flow)). We actively welcome your pull requests:
+
+Pull requests are the best way to propose changes to the codebase (we use
+[Github Flow](https://docs.github.com/en/get-started/quickstart/github-flow)).
+We actively welcome your pull requests:
 
 1. Fork the repo and create your branch from `main`.
-2. If you've added code that should be tested, add tests.
+2. Make your changes.
-4. Ensure the test suite passes.
+3. Issue your pull request!
-5. Make sure your code lints.
-6. Issue your pull request!
 
 ## Any contributions you make will be under the MIT Software License
-In short, when you submit code changes, your submissions are understood to be under the same [MIT License](http://choosealicense.com/licenses/mit/) that covers the project. Feel free to contact the maintainers if that's a concern.
 
-## Report bugs using Github's [issues](https://github.com/sailpoint-oss/developer.sailpoint.com/issues)
+In short, when you submit code changes, your submissions are understood to be
-We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/sailpoint-oss/developer.sailpoint.com/issues/new); it's that easy!
+under the same [MIT License](http://choosealicense.com/licenses/mit/) that
+covers the project.
 
-## Write bug reports with detail, background, and sample code
+# Report Bugs Using Our Repository's [issues](https://github.com/sailpoint-oss/developer.sailpoint.com/issues)
 
-**Great Bug Reports** tend to have:
+People _love_ thorough bug reports. We use GitHub issues to track bugs publicly.
+Report a bug by
+[opening a new bug](https://github.com/sailpoint-oss/developer.sailpoint.com/issues/new?assignees=&labels=&template=bug-report.md&title=%5BBug%5D+Your+Bug+Report+Here);
+it's that easy!
 
-- A quick summary and/or background
+## Write Bug Reports With Detail, Background, and Sample Code
+
+**Great bug reports** tend to have:
+
+- A quick summary and/or description
 - Steps to reproduce
   - Be specific!
   - Give sample code if you can.
 - What you expected would happens
 - What actually happens
-- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
+- Screenshots!
+- Operating System
+- Browser
+- Notes (possibly including why you think this might be happening, or stuff you
+  tried that didn't work)
 
-People *love* thorough bug reports.
+# Make A Feature Request Using Our Repository's [issues](https://github.com/sailpoint-oss/developer.sailpoint.com/issues)
 
-## Use a Consistent Coding Style
+We use GitHub issues to track feature requests. Request a feature request by
+[opening a new feature request](https://github.com/sailpoint-oss/developer.sailpoint.com/issues/new?assignees=&labels=&template=feature-request.md&title=%5BFeature%5D+Your+Feature+Request+Here);
+it's that easy!
 
-* 2 spaces for indentation rather than tabs
+## Write Feature Requests With Detail
-* You can try running `npm run lint` for style unification
 
-## License
+**Great feature requests** tend to:
-By contributing, you agree that your contributions will be licensed under its MIT License.
+
+- Say if this is related to a problem (and describe said problem)
+- Describe the solution you'd like
+- Describe alternatives you use or have considered
+- Notes (possibly including why you think this might benefit others, too)
+
+# Submit a Fix
+
+Looking to take on fixing something yourself? Great! Here's the short on how to
+do it:
+
+- Fork the repository, copy the main branch only
+- Pull down the code, build, and ensure it's running properly
+- Create a new branch from main with the naming convention `fix/your-fix-name`
+- Create a pull request from your branch to our origin repository's main branch!
+
+# Submit a New Feature
+
+Looking to take on adding a new feature? Great! Here's the short on how to do
+it:
+
+- Fork the repository, copy the main branch only
+- Pull down the code, build, and ensure it's running properly
+- Create a new branch from main with the naming convention
+  `feature/your-feature-name`
+- Create a pull request from your branch to our origin repository's main branch!
+
+# Discuss, Submit General Issue, or Ask a Question
+
+If none of the above work, you can submit a general issue using GitHub's
+[issues](https://github.com/sailpoint-oss/developer.sailpoint.com/issues). You
+can also head over to the
+[Developer Community forum](https://developer.sailpoint.com/discuss) to discuss
+with us directly on the forum about what you're thinking!
+
+- 2 spaces for indentation rather than tabs
+- You can try running `npm run lint` for style unification
+
+# License
+
+By contributing, you agree that your contributions will be licensed under its
+MIT License.

README.md

@@ -4,11 +4,15 @@
 ![Latest Releases][release-shield] ![Contributor Shield][contributor-shield]
 [![Deploy to Production](https://github.com/sailpoint-oss/developer.sailpoint.com/actions/workflows/build-and-deploy-prod-gh-pages.yml/badge.svg)](https://github.com/sailpoint-oss/developer.sailpoint.com/actions/workflows/build-and-deploy-prod-gh-pages.yml)
 
-[discourse-shield]: https://img.shields.io/discourse/topics?label=Discuss%20This%20Tool&server=https%3A%2F%2Fdeveloper.sailpoint.com%2Fdiscuss
+[discourse-shield]:
+  https://img.shields.io/discourse/topics?label=Discuss%20This%20Tool&server=https%3A%2F%2Fdeveloper.sailpoint.com%2Fdiscuss
 [discourse-url]: https://developer.sailpoint.com/discuss/
-[issues-shield]: https://img.shields.io/github/issues/sailpoint-oss/developer.sailpoint.com?label=Issues
+[issues-shield]:
-[release-shield]: https://img.shields.io/github/v/release/sailpoint-oss/developer.sailpoint.com?label=Current%20Release
+  https://img.shields.io/github/issues/sailpoint-oss/developer.sailpoint.com?label=Issues
-[contributor-shield]: https://img.shields.io/github/contributors/sailpoint-oss/developer.sailpoint.com?label=Contributors
+[release-shield]:
+  https://img.shields.io/github/v/release/sailpoint-oss/developer.sailpoint.com?label=Current%20Release
+[contributor-shield]:
+  https://img.shields.io/github/contributors/sailpoint-oss/developer.sailpoint.com?label=Contributors
 
 <!-- PROJECT LOGO -->
 <br />
@@ -27,17 +31,26 @@
 ## About The Project
 
 This repository contains the complete build, with assets, for everything seen on
-developer.sailpoint.com. The includes the homepage, all static elements,
+developer.sailpoint.com. This includes the homepage, all static elements,
-documentation, API specifications, et. al. The API specifications come in from a
+_documentation_, API specifications, et. al. The API specifications come in from
-GitHub Action in another repository, but ultimately the API specifications used
+a GitHub Action in another repository, but ultimately the API specifications
-to generate this static site are those found in the `static` folder.
+used to generate this static site are those found in the `static` folder.
 
-Please use GitHub issues to submit bugs or make feature requests.
+Please use GitHub
+[issues](https://github.com/sailpoint-oss/developer.sailpoint.com/issues) to
+[submit bugs](https://github.com/sailpoint-oss/developer.sailpoint.com/issues/new?assignees=&labels=&template=bug-report.md&title=%5BBug%5D+Your+Bug+Report+Here)
+or make
+[feature requests](https://github.com/sailpoint-oss/developer.sailpoint.com/issues/new?assignees=&labels=&template=feature-request.md&title=%5BFeature%5D+Your+Feature+Request+Here).
+
+If you'd like to contribute directly (which we encourage!) please read the
+contribution guidelines below, first!
 
 <!-- GETTING STARTED -->
 
 ## Getting Started
 
+If you want to build this project locally, follow the steps below.
+
 ### Prerequisites
 
 To run this project you must first have npm installed.
@@ -49,36 +62,29 @@ npm install npm@latest -g
 ### Installation
 
 1. Clone the repo
+
    ```bash
    git clone https://github.com/sailpoint-oss/developer.sailpoint.com.git
    ```
-2. Install NPM packages
+
+2. Install the project's NPM packages
+
    ```bash
    npm install
    ```
-3. Generate the docs
+
+3. Generate the API docs. They are auto-generated, so we do not track them in
+   the repository and instead build them at runtime.
+
    ```bash
    npm run gen-api-docs-all
    ```
+
 4. Start the website
    ```bash
    npm run start
    ```
 
-### Running the Algolia crawler
-
-1. Setup a .env file inside the algolia folder
-   ```sh
-   APPLICATION_ID={APP_ID}
-   API_KEY={API_KEY}
-   ```
-2. Run the Algolia crawler using docker
-   ```
-   docker run -it --env-file=./algolia/.env -e "CONFIG=$(cat ./algolia/config.json | jq -r tostring)" algolia/docsearch-scraper
-   ```
-
-<!-- CONTACT -->
-
 ## Discuss
 
 [Click Here](https://developer.sailpoint.com/discuss) to discuss this tool with
@@ -95,9 +101,10 @@ information.
 
 ## Contributing
 
-Before you contribute you must sign our CLA. Please also read our
+Before you contribute you
-[contribution guidelines](./CONTRIBUTING.md) for all the details on
+[must sign our CLA](https://cla-assistant.io/sailpoint-oss/developer.sailpoint.com).
-contributing.
+Please also read our [contribution guidelines](./CONTRIBUTING.md) for all the
+details on contributing.
 
 <!-- CODE OF CONDUCT -->