From d3722291e2a7d03424ef967a7b93dc9bfb9cc0b4 Mon Sep 17 00:00:00 2001 From: raglandconnor Date: Wed, 25 Sep 2024 16:34:53 -0400 Subject: [PATCH] Update README for clarity. Modified project install, getting started, workflow, and testing sections. --- README.md | 50 +++++++++++++++++++++++++++++++++++--------------- 1 file changed, 35 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index b16e2b6..dbec98e 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,9 @@ This project has two Github pages this is designated for the Backend Development ## Project Install One-Liner -Copy this command to quickly get started. Must have docker, docker-compose, and git installed. +Copy this command to quickly get started. + +Make sure docker, docker-compose, and git installed on your machine. ```sh git clone git@github.com:ufosc/Jukebox-Server.git && cd Jukebox-Server && cp sample.env .env && docker-compose up --build @@ -30,18 +32,29 @@ git clone git@github.com:ufosc/Jukebox-Server.git && cd Jukebox-Server && cp sam ## Getting started -Use the following commands to download the project locally and get it running with nodemon. +Follow these steps to download the project locally and get it running with nodemon. + +1. Clone the repository: ```sh git clone cd Jukebox-Server +``` +2. Set up the environment: + +```sh cp sample.env .env +``` + +3. Build and run the Docker containers: + +```sh docker-compose build docker-compose up ``` -We use docker compose to easily connect to databases and other container images. It could alternatively be run using `npm run dev`; however, this is not guaranteed to always work. +We use Docker Compose to manage the server and its dependencies, including databases and other containers. While you can run the server using `npm run dev`, Docker Compose provides more reliability. Once the server is running, visit to authenticate with Spotify. @@ -61,34 +74,41 @@ Once the server is running, visit to authenticate ## Workflow -To start with, look over the issues list and either pick out a task from there, or you can plan out your own idea. After that, clone the main branch onto you local system and get the server up and running using the commands above. +1. Start by reviewing the [issues list](https://github.com/ufosc/Jukebox-Server/issues) and pick a task or propose a new feature. -Once you have the server up and running, create a feature branch and start coding! +2. Clone the main branch onto your local system: ```sh -git checkout -b feature/something-brilliant +git clone git@github.com:ufosc/Jukebox-Server.git && cd Jukebox-Server && cp sample.env .env && docker-compose up --build ``` -Remember, branches need to be focused on specific and full-working features. These features can be small, like adding some documentation, or large, like adding advanced authentication. +3. Create a feature branch **(ensure your branch focuses on a specific, fully working feature e.g. documentation, implementing new authentication logic)**: -After you are finished with the feature, make sure you have written at least 3 unit tests, otherwise the pull request might not be accepted. Ideally, you should write tests before making the new feature to follow with the TDD paradigm, but this takes a bit of practice. -Include Link/Example to TDD Paradigm here. +```sh +git checkout -b feature-name +``` -After you are satisfied, push your branch to GitHub and submit a pull request for you new branch. +Before submitting a pull request, write at least three unit tests. If possible, follow the Test-Driven Development (TDD) paradigm, which involves writing tests before coding the feature itself. [Learn more about TDD here](https://www.browserstack.com/guide/what-is-test-driven-development). -The pull request will then be tested by a maintainer, and merged into the main branch. +4. Push your feature branch and submit a pull request (PR). Your PR will be reviewed and tested by a maintainer before merging. ## Testing -When creating unit tests please use Mocha Formatting. REMEMBER TO HAVE AT LEAST 3 UNIT TESTS. +We use Mocha for unit testing. **At least 3 unit tests** must accompany any new feature. + +Example of Mocha Formatting: + +``` var expect = require("chai").expect; var converter = require("../app/converter"); + describe("JukeboxTest", function() { -// specification code -// Play from this specific playlist, source from another artist, etc. +// Specification code +// e.g., Play from this specific playlist, source from another artist, etc. }); +``` -Running the following command will run Mocha, which will look for files inside the `/test` directory. +To run the tests, use the following command. This will run Mocha, which will look for test files inside the `/test` directory: ```sh docker-compose run --rm api sh -c "npm test"