Merge pull request #21 from HCloward/add-contrib-guide

docs: updates readme and adds contribution guide

CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Museum OpenAPI example contributing guide
+
+Hi! We're really excited that you are interested in contributing to the Museum OpenAPI example.
+Before submitting your contribution though, please make sure to take a moment and read through the following guidelines.
+
+- [Museum OpenAPI example contributing guide](#museum-openapi-example-contributing-guide)
+  - [Issue reporting guidelines](#issue-reporting-guidelines)
+  - [Pull request guidelines](#pull-request-guidelines)
+  - [Development setup](#development-setup)
+  - [Contribute documentation](#contribute-documentation)
+    - [Configuration file](#configuration-file)
+  - [Project structure](#project-structure)
+  - [Release flow](#release-flow)
+
+## Issue reporting guidelines
+
+- Before opening a new issue, check that the same problem or idea hasn't already been reported.
+  You can do that on the [Issues page](https://github.com/Redocly/museum-openapi-example/issues) in the repository and using the filter `is:issue` combined with some keywords relevant to your idea or problem.
+  It helps us notice that more people have the same issue or use-case, and reduces the chance of getting your issue marked as a duplicate.
+  Plus, you can even find some workarounds for your issue in the comments of a previously reported one!
+
+- The best way to get your bug fixed is to provide a (reduced) test case.
+  A test case means listing and explaining the steps we should take to try and hit the same problem you're having.
+  It helps us understand in which conditions the issue appears, and gives us a better idea of what may be causing it.
+
+- Abide by our [Code of Conduct](https://redocly.com/code-of-conduct/) in all your interactions on this repository, and show patience and respect to other community members.
+
+## Pull request guidelines
+
+Before submitting a pull request, please make sure the following is done:
+
+1. Fork the repository and create your branch from `main`.
+2. Clone the repo to your local device, so you can run it and test visually before submitting your changes.
+3. Create a branch from `main` before making any updates.
+4. Make you updates to the `openapi.yaml` file.
+5. Run `npm install` in the repository root to see your updates locally.
+6. Once you are happy with your updates, commit and push your updates to your fork.
+7. Open a PR from your repo/branch to the Redocly repo/main.
+
+## Development setup
+
+[Node.js](http://nodejs.org) at v14.19.0+ and NPM v7.0.0+ are required.
+
+After cloning the repo, install the Redocly CLI by running the following command:
+
+```bash
+npm install # or npm i
+```
+
+To preview the Museum OpenAPI example's docs and your changes, run the following command:
+
+```bash
+npm run preview
+```
+
+## Contribute documentation
+
+Additions and updates to our documentation are very welcome.
+
+
+### Configuration file
+
+The **redocly.yaml** file is the  
+Please refer to the [configuration file](https://redocly.com/docs/cli/configuration/) documentation for more details.
+
+## Project structure
+
+- **`docs`**: contains the documentation source files. 
+When changes to the documentation are merged, they automatically get published on the [Redocly docs website](https://redoc.ly/docs/cli/).
+
+
+## Release flow
+
+If the pipelines are not starting, close and reopen the PR. Merging that PR triggers the release process.

README.md

@@ -1,19 +1,23 @@
 # Redocly Museum API Example
 
-An imaginary, but delightful Museum API for interacting with museum services and information. Built by Redocly for educational purposes. Enjoy!
+An imaginary, but delightful Museum API for interacting with museum services and information.
+Built by Redocly for educational purposes.
+Enjoy!
 
 > [!NOTE]  
 > This OpenAPI description uses the [OpenAPI 3.1.0 specification](https://spec.openapis.org/oas/v3.1.0).
 
 ## Overview
 
-Introducing the "Museum API", which offers a set of endpoints to interact with a museum's services--such as retrieving museum hours, managing special events, and purchasing tickets. 
+Introducing the "Museum API", which offers a set of endpoints to interact with a museum's services--such as retrieving museum hours, managing special events, and purchasing tickets.
 
-New functionality may be added to the Museum API in the future. Is there an example you'd like to see? Please [open an issue](https://github.com/Redocly/museum-openapi-example/issues/new).
+New functionality may be added to the Museum API in the future.
+Is there an example you'd like to see? Please [open an issue](https://github.com/Redocly/museum-openapi-example/issues/new).
 
 ## Features
 > [!NOTE]  
-> Reminder that this is a fictional example for learning purposes. The features below are only for learning.
+> Reminder that this is a fictional example for learning purposes.
+> The features below are only for learning.
 
 The Museum API has the following core features (sorted by tags):
 - Operations
@@ -35,9 +39,10 @@ The Museum API has the following core features (sorted by tags):
 
 ### Working with the OpenAPI description
 
-We encourage you to explore the museum's OpenAPI description and make changes. Try experimenting with the following approaches:
+We encourage you to explore the museum's OpenAPI description and make changes.
+Try experimenting with the following approaches:
 
-**Preview the museum's API docs and observe your changes visually.**
+**Preview the Museum OpenAPI example's API docs and observe your changes visually.**
 - Run `npm run preview` to preview the documentation.
 - Navigate to the **List special events** operation in the preview.
 - With the preview running...
@@ -68,4 +73,6 @@ See the updated description? This is a great way to preview how end-users of you
 ```
 - Run `npm run lint` in your terminal. See the errors? 
 
-The linting behavior is controlled by the _redocly.yaml_ configuration file. The linter is configured to use Redocly's [recommended ruleset](https://redocly.com/docs/cli/rules/recommended/#recommended-ruleset), which are built into the CLI. However, we also added a [configurable rule](https://redocly.com/docs/cli/rules/configurable-rules/) for enforcing sentence casing on operation summaries. 
+The linting behavior is controlled by the _redocly.yaml_ configuration file.
+The linter is configured to use Redocly's [recommended ruleset](https://redocly.com/docs/cli/rules/recommended/#recommended-ruleset), which are built into the CLI.
+However, we also added a [configurable rule](https://redocly.com/docs/cli/rules/configurable-rules/) for enforcing sentence casing on operation summaries.