docs(core): Improve clarity and add contributing section (#3580)

Co-authored-by: HouseinIsProgramming <76689341+GogoIsPrograming@users.noreply.github.com>

README.md

@@ -43,6 +43,16 @@ vendure/
     ├── docs/       # Scripts used to generate documentation markdown from the source
 ```
 
+## Contributing
+
+You are very much welcome to contribute to Vendure, we appreciate every pull request made, issue reported or any other form of feedback or input. 
+
+Before getting started, please read our [Contribution Guidelines](https://github.com/vendure-ecommerce/vendure/blob/master/CONTRIBUTING.md) first to make the most out of your time and ours.
+
+If you're looking for a place to start, check out our [list of issues labeled "contributions welcome"](https://github.com/vendure-ecommerce/vendure/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22contributions%20welcome%22).
+
+Thank you for considering making Vendure better!
+
 ## Development
 
 > [!IMPORTANT]
@@ -62,7 +72,7 @@ The root directory has a `package.json` which contains build-related dependencie
 
 `npm run build`
 
-Packages must be built (i.e. TypeScript compiled, admin ui app built, certain assets copied etc.) before being used.
+Packages must be built (i.e. TypeScript compiled, Admin UI app built, certain assets copied etc.) before being used.
 
 Note that this can take a few minutes.
 
@@ -85,77 +95,124 @@ docker-compose up -d elasticsearch
 
 ### 4. Populate test data
 
-Vendure uses [TypeORM](http://typeorm.io), and officially supports **MySQL**, **MariaDB**, **PostgreSQL** and **SQLite**.
+Vendure uses [TypeORM](http://typeorm.io) and officially supports **MySQL**, **MariaDB**, **PostgreSQL**, and **SQLite**.
 
 The first step is to populate the dev server with some test data:
 
 ```bash
 cd packages/dev-server
+npm run populate
+```
+
+By default, if you do not specify the `DB` environment variable, it will use **MySQL/MariaDB**.
 
-[DB=mysql|postgres|sqlite] npm run populate
+If you want to develop against **PostgreSQL**:
+
+1. Run the `postgres_16` Docker container.
+```bash
+docker-compose up -d postgres_16
 ```
+2. Create a .env file in `/packages/dev-server` and declare the `DB` variable inside it:
 
-If you do not specify the `DB` variable, it will default to "mysql". If you specifically want to develop against Postgres,
-you need to run the `postgres_16` container and then run `DB=postgres npm run populate`.
+    ```env
+    DB=postgres
+    ```
+3. Now run the npm populate script.
+
+> [!TIP]
+> You can also set the environment variable directly in the CLI:
+>
+> ```bash
+> DB=postgres npm run populate
+> ```
 
 ### 5. Run the dev server
 
-```
+```bash
 cd packages/dev-server
-[DB=mysql|postgres|sqlite] npm run dev
+npm run dev
 ```
 
-### Testing admin ui changes locally
+This will start the development server, and you should see output in your terminal indicating that the **Vendure development server** has successfully started.
+
+The output lists the available endpoints for the Shop API, Admin API, GraphiQL interfaces, asset server, development mailbox, and the Admin UI, along with their respective URLs.
+
+You can now access these services in your browser for development and testing.
+
+Default Admin UI credentials:
+
+Username: `superadmin`
+Password: `superadmin`
+
+
+### Testing Admin UI changes locally
 
-If you are making changes to the admin ui, you need to start the admin ui independent from the dev-server:
+If you are making changes to the Admin UI, you need to start the Admin UI independent from the dev-server:
 
-1. `cd packages/admin-ui`
-2. `npm run dev`
-3. Go to http://localhost:4200 and log in with "superadmin", "superadmin"
+> [!NOTE] 
+> You don't need this step when you just use the Admin UI just
+to test backend changes since the `dev-server` package ships with a default admin-ui
 
-This will auto restart when you make changes to the admin ui. You don't need this step when you just use the admin ui just
-to test backend changes.
+
+```
+cd packages/admin-ui
+npm run dev
+```
+
+This will run a separate process of admin-ui on "http://localhost:4200", you can login with the default credentials:
+
+Username: `superadmin`
+Password: `superadmin`
+
+This will auto restart when you make changes to the Admin UI. 
 
 ### Testing your changes locally
 
-This example shows how to test changes to the `payments-plugin` package locally, but it will also work for other packages.
+This example shows how to test changes to the `payments-plugin` package locally. 
+This same workflow can be used for other packages as well.
 
-1. Open 2 terminal windows:
+### Terminal Setup
 
-- Terminal 1 for watching and compiling the changes of the package you are developing
-- Terminal 2 for running the dev-server
+**In 2 separate terminal windows:**
 
-```shell
-# Terminal 1
+**Terminal 1** - Watch changes to the package:
+
+```bash
 cd packages/payments-plugin
 npm run watch
 ```
 
-:warning: If you are developing changes for the `core`package, you also need to watch the `common` package:
-
-```shell
-# Terminal 1
-# Root of the project
-npm run watch:core-common
+**Terminal 2** - Run the development server:
+```bash
+cd packages/dev-server
+npm run dev
 ```
 
-2. After the changes in your package are compiled you have to stop and restart the dev-server:
+> [!NOTE]
+> After making changes, you need to stop and restart the development server to see your changes.
+
+> [!WARNING] 
+> If you are developing changes for the `core` package, you also need to watch the `common` package:
 
+in the root of the project:
 ```shell
-# Terminal 2
-cd packages/dev-server
-DB=sqlite npm run dev
+npm run watch:core-common
 ```
 
-3. The dev-server will now have your local changes from the changed package.
+#### Development Workflow Summary
+1. Start your package watcher (npm run watch)
+2. Start the dev-server (npm run dev)
+3. Make code changes
+4. Wait for compilation to complete
+5. Restart dev-server to see changes
 
 ### Interactive debugging
 
-To debug the dev server with VS Code use the include [launch.json](/.vscode/launch.json) configuration.
+To debug the dev server with VS Code use the included [launch.json](/.vscode/launch.json) configuration.
 
 ### Code generation
 
-[graphql-code-generator](https://github.com/dotansimha/graphql-code-generator) is used to automatically create TypeScript interfaces for all GraphQL server operations and admin ui queries. These generated interfaces are used in both the admin ui and the server.
+[graphql-code-generator](https://github.com/dotansimha/graphql-code-generator) is used to automatically create TypeScript interfaces for all GraphQL server operations and Admin UI queries. These generated interfaces are used in both the Admin UI and the server.
 
 Running `npm run codegen` will generate the following files:
 
@@ -169,7 +226,7 @@ Running `npm run codegen` will generate the following files:
 
 #### Server Unit Tests
 
-The core and several other packages have unit tests which are can be run all together by running `npm run test` from the root directory, or individually by running it from the package directory.
+The core and several other packages have unit tests which can be run all together by running `npm run test` from the root directory, or individually by running it from the package directory.
 
 Unit tests are co-located with the files which they test, and have the suffix `.spec.ts`.
 
@@ -199,7 +256,7 @@ Finally, the command will create changelog entries for this release and create a
 
 ##### 2. `git push origin master --follow-tags`
 
-The reason we do not rely on Lerna to push the release to Git is that this repo has a lengthy pre-push hook which runs all tests and builds the admin ui. This long wait then invalidates the npm OTP and the publish will fail. So the solution is to publish first and then push.
+The reason we do not rely on Lerna to push the release to Git is that this repo has a lengthy pre-push hook which runs all tests and builds the Admin UI. This long wait then invalidates the npm OTP and the publish will fail. So the solution is to publish first and then push.
 
 ##### 3. Create a GitHub release