From 370d8128a509ad60d544cfd022a79e7bf2570ff5 Mon Sep 17 00:00:00 2001 From: Davie Date: Thu, 27 Aug 2026 14:01:46 +1000 Subject: [PATCH] Update contributing setup documentation --- CONTRIBUTING.md | 92 +++++++++++++++++++++---------------------------- 1 file changed, 39 insertions(+), 53 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b704a576a..c96068e38 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,6 +12,8 @@ This guide provides high-level details on how to contribute to the Doubtfire rep - [Table of Contents](#table-of-contents) - [Getting started](#getting-started) - [Development Containers](#development-containers) + - [Common setup](#common-setup) + - [Working with Dev Containers](#working-with-dev-containers) - [Working with Docker Compose](#working-with-docker-compose) - [Forking workflow](#forking-workflow) - [About the Doubtfire Branch Structure](#about-the-doubtfire-branch-structure) @@ -27,7 +29,7 @@ This guide provides high-level details on how to contribute to the Doubtfire rep The **doubtfire-deploy** project provides the base repository containing submodules for each of the specific subprojects. - [doubtfire-api](https://github.com/doubtfire-lms/doubtfire-api) contain the backend RESTful API. This uses Rails' [active model](https://guides.rubyonrails.org/active_model_basics.html) with the [Grape REST api framework](https://github.com/ruby-grape/grape). -- [doubtfire-web](https://github.com/doubtfire-lms/doubtfire-web) hosts the frontend code implemented in [Angular](https://angular.io) and [AngularJS](https://angularjs.org). This implements the web application that connects to the backend api. +- [doubtfire-web](https://github.com/doubtfire-lms/doubtfire-web) hosts the frontend code implemented in Angular 22. This implements the web application that connects to the backend API. - [doubtfire-overseer](https://github.com/doubtfire-lms/doubtfire-overseer) provides facilities to run automated tasks on student submissions. Please get in touch with the core team if you want access to this repository. You can make contributions without access to this repository. Development of Doubtfire uses Docker containers to remove the need to install a range of native tools used within the project. The Doubtfire Deploy project helps when working across multiple components of the Doubtfire application, and is used for testing and publishing versions for deployment. @@ -41,85 +43,69 @@ There are several docker compose setups to aid in speeding up the development. - The **docker-compose.yml** file contains the most likely setup with development setups for both the api and web projets. This should be used when working on both the api and the web front end. You can run this using **run-api-web.sh**. - The **docker-compose.full.yml** contains a setup with all of the containers needed to run Doubtfire with overseer. This requires access to the overseer repository. You can run this using **run-full.sh** -### Working with Dev Containers - -This is the primary method for setting up your development enviroment: - -Pre requisittes: Vscode, Docker -OS: Windows/Linux/Mac OS +### Common setup -1. Fork [doubtfire-deploy](https://github.com/doubtfire-lms/doubtfire-deploy), [doubtfire-api](https://github.com/doubtfire-lms/doubtfire-api), and [doubtfire-web](https://github.com/doubtfire-lms/doubtfire-web) +1. Fork [doubtfire-deploy](https://github.com/doubtfire-lms/doubtfire-deploy), [doubtfire-api](https://github.com/doubtfire-lms/doubtfire-api), and [doubtfire-web](https://github.com/doubtfire-lms/doubtfire-web). - To push your contributions, you will need a fork of each repository. Contributions can then be made by making pull requests back into the main repositories. + To push your contributions, you will need a fork of each repository. Contributions can then be made by making pull requests back into the main repositories. 2. Clone your [doubtfire-deploy](https://github.com/doubtfire-lms/doubtfire-deploy). Make sure to fetch submodules to get the subprojects. - `git clone --recurse-submodules https://github.com/YOUR_USERNAME/doubtfire-deploy` + `git clone --recurse-submodules https://github.com/YOUR_USERNAME/doubtfire-deploy` -3. Open a Terminal that supports `sh` scripts (on Windows, you will need WSL, Msys2, or Cygwin). Run the following command to set your fork as the remote. +3. Open a Terminal that supports `sh` scripts (on Windows, you will need WSL, MSYS2, or Cygwin). Run the following command to set your fork as the remote. - `./change_remotes.sh` + `./change_remotes.sh` -4. In Visual studio press F1: Find Dev Containers: Open folder in Container (This will reopen the repo you cloned in a container) +4. Open a web browser and navigate to: -5. The container will automaticlly setup the DB, Frontend, Backend and your development enviroment ready for use. + - [http://localhost:3000/api/docs/](http://localhost:3000/api/docs/) to interact with the API using [Swagger](https://swagger.io). + - [http://localhost:4200](http://localhost:4200) to use the web application. -6. Open a web browser and navigate to: + The database will include a number of default users, each with password being "password". - - [http://localhost:3000/api/docs/](http://localhost:3000/api/docs/) to interact with the API using [Swagger](https://swagger.io). - - [http://localhost:4200](http://localhost:4200) to use the web application. + - Admin user: **aadmin** + - Convenor user: **aconvenor** + - Tutor user: **atutor** + - Students: **student_1** - The database will include a number of default users, each with password being "password". - - Admin user: **aadmin** - - Convenor user: **aconvenor** - - Tutor user: **atutor** - - Students: **student_1** +### Working with Dev Containers -### Working with Docker Compose +This is the primary method for setting up your development environment. -Alternative setup using Docker-Compose: +Prerequisites: VS Code, Docker +OS: Windows/Linux/macOS -1. Fork [doubtfire-deploy](https://github.com/doubtfire-lms/doubtfire-deploy), [doubtfire-api](https://github.com/doubtfire-lms/doubtfire-api), and [doubtfire-web](https://github.com/doubtfire-lms/doubtfire-web) +Follow the [Common setup](#common-setup) steps first, then: - To push your contributions, you will need a fork of each repository. Contributions can then be made by making pull requests back into the main repositories. +1. In Visual Studio Code, press F1 and select **Dev Containers: Open Folder in Container**. This will reopen the repository you cloned in a container. -2. Clone your [doubtfire-deploy](https://github.com/doubtfire-lms/doubtfire-deploy). Make sure to fetch submodules to get the subprojects. +2. The container will automatically set up the DB, frontend, backend, and your development environment ready for use. - `git clone --recurse-submodules https://github.com/YOUR_USERNAME/doubtfire-deploy` +### Working with Docker Compose -3. Open a Terminal that supports `sh` scripts (on Windows, you will need WSL, Msys2, or Cygwin). Run the following command to set your fork as the remote. +Alternative setup using Docker Compose. - `./change_remotes.sh` +Follow the [Common setup](#common-setup) steps first, then: -4. Change into the **development** directory and use [Docker Compose](https://docs.docker.com/compose/) to setup the database. +1. Change into the **development** directory and use [Docker Compose](https://docs.docker.com/compose/) to set up the database. - ```bash - cd development - docker compose run --rm doubtfire-api bash - # now in the container run... - bundle exec rails db:environment:set RAILS_ENV=development - bundle exec rake db:populate - exit - ``` + ```bash + cd development + docker compose run --rm doubtfire-api bash + # now in the container run... + bundle exec rails db:environment:set RAILS_ENV=development + bundle exec rake db:populate + exit + ``` -5. Now you can use `docker compose` to start a running environment. +2. Use `docker compose` to start a running environment. ```bash # Run in the development folder docker compose up ``` -6. Open a web browser and navigate to: - - - [http://localhost:3000/api/docs/](http://localhost:3000/api/docs/) to interact with the API using [Swagger](https://swagger.io). - - [http://localhost:4200](http://localhost:4200) to use the web application. - - The database will include a number of default users, each with password being "password". - - Admin user: **aadmin** - - Convenor user: **aconvenor** - - Tutor user: **atutor** - - Students: **student_1** - To interact with the rails console, or other rails command line applications: - Connect to a **doubtfire-api** container: @@ -134,7 +120,7 @@ Alternative setup using Docker-Compose: - Run all unit tests using: `bundle exec rails test` - Run tests from a single file: `bundle exec rails test test/models/break_test.rb` - Run a single test: `bundle exec rails test test/api/auth_test.rb:107` - - Setup the databse: + - Set up the databse: - Reset the database: `bundle exec rake db:reset db:migrate` - Migrate the database on schema changes: `bundle exec rake db:migrate` - Add a new migration: `bundle exec rails g migration migration-name` @@ -152,7 +138,7 @@ Alternative setup using Docker-Compose: Some things to know about the setup: - The containers link to `../data` as a volume to store database details, tmp files, and student work. - - If you do not gracefully terminal the api you may need to remove the `pid` file from the tmp folder. You can use `rm ../data/tmp/pids/server.pid` to do this. + - If you do not gracefully terminate the API you may need to remove the `pid` file from the tmp folder. You can use `rm ../data/tmp/pids/server.pid` to do this. - When you bring up the *doubtfire-web* project, it will run `npm install` to setup the node_modules. If you change the package.json in *doubtfire-web* you can just restart the container to update the node modules. ## Forking workflow