Skip to content

Developer Guide

Jump to bottom
Joshua Kitenge edited this page Aug 23, 2024 · 14 revisions

Workflow

  1. Select a issue from the IMS issues.
  2. Pull the latest version of the develop branch
  3. Create a branch from there called #{insert label (e.g feature or bug)}/{insert general name of story}-#{story number}
  4. Put the issue into In Progress
  5. Repeatedly during development:
    1. Develop code/write tests
    2. Ensure all tests pass
    3. Run linter and fix issues
    4. Commit - ideally, each commit message should have the issue number included, so that we can track the code related to resolving the issue
    5. (optionally) push to origin
  6. Merge origin/develop into your feature branch.
  7. Run unit tests
  8. Check impact on coverage
  9. Run e2e tests
  10. Push to origin
  11. Make a pull request - the PR description should also point to the relevant issue
  12. Put the issue into In Review
  13. Get the pull request reviewed, if more work needs to be done go back to step 4.
  14. Wait for the automated build (if it exists, otherwise the reviewer should do these steps)
  15. Once a pull request is approved then it can be merged back into origin/develop
  16. Wait for the automated build for the merge in to develop to pass.
  17. Move the issue to Done and close the issue.

Branching Strategy

When working on a new feature the branch should follow the naming convention feature/{insert general name of story}-#{story number}. This indicates it is new functionality as well as linking it to the story (for potential future requirement tracing)

If working on a bug from a previous story then the branch should follow the pattern bugfix/{general name of bug}-#{story/bug number}.

Required Tools

To develop the Inventory management system you will need the following tools:

  • Node.js (https://nodejs.org/en/) - (LTS version at the time of writing is 20.17.0)
  • NPM (comes with the node.js installation)
  • An IDE for developing with JavaScript (VS Code is a good cross-platform suggestion)
  • Yarn
  • Docker
  • Docker Compose

Installation instructions are available on the sites for each tool and depend on your operating system, e.g. node can be installed as an msi on a windows machine

Note: if installing Node.js on Linux machines please read https://nodejs.org/en/download/package-manager/ as these detail how to ensure you are able to get the most recent version of Node.js on your machine, rather than an old version in the default package.

Helpful tools

  • React Dev Tools extension: Chrome Firefox
  • Redux Dev Tools extension: http://extension.remotedev.io/
  • Useful VSCode extensions:
    • JavaScript development:
      • ESLint - displays eslint errors in the editor
      • npm Intellisense - autocompletes npm import statements
      • npm - validates that dependencies are installed and adds NPM commands to command pallete
      • Prettier - can format files using Prettier - I have it set to format on save ;)
    • Git:
      • GitLens - enhances VSCode git support
    • General:
      • Code Coverage - highlights uncovered lines of code in the editor

New developer tutorials

Here's a list of useful tutorials to help new developers learn the technologies required:

Starting the Inventory Management System for development

First of all, you will need to clone the repository and navigate to the project directory:

git clone git@github.com:ral-facilities/inventory-management-system.git
cd inventory-management-system

Create a inventory-management-system-settings.json file

cp public/inventory-management-system-settings.example.json public/inventory-management-system-settings.json

Run install all the dependancies

yarn install

When switching branches you may need to run yarn install if the branch you are on has installed extra dependencies

If you get errors about dependencies not being met, especially after switching branches, then this may be due to yarn having mismatching versions and getting stuck and unable to upgrade. This can usually be fixed by deleting the node_modules folder and running yarn install freshly

Starting Dev serve with Mock data (MSW)

Local

Start the website

yarn dev

Docker

Build and start the Docker containers:

docker-compose up

The website should now be running at http://localhost:3000.

Starting the Dev serve with IMS API

Start IMS API (using docker-compose.yml)

IMS API should be running http://localhost:8000. To check if it is running correctly you access the open api docs.

Edit the apiUrl in the inventory-management-system-settings.json to be

  • 'http://localhost:8000'

Local

Start the website

yarn dev

Docker

Build and start the Docker containers:

docker-compose up

The website should now be running at http://localhost:3000.

Starting IMS with Scigateway with authentication

Start IMS API (using docker-compose.yml)

IMS API should be running http://localhost:8000.

Edit the apiUrl in the inventory-management-system-settings.json to be

  • 'http://localhost:8000'

Start ldap-jwt-auth (using docker-compose.yml)

ldap-jwt-auth should be running http://localhost:8001.

Start Scigateway(on react-18 branch react-18-#1205)

{
   "plugins": [
     {
      "name": "inventory-managment-system",
      "src": "http://localhost:5001/main.js",
      "enable": false,
      "location": "main"
     }
   ],
   "auth-provider": "jwt",
   "authUrl":"http://localhost:8001"
}

Starting IMS

Start the website

yarn bulid:preview

This should build the main.js on http://localhost:5001.

Without authentication

  • Skip these step Start ldap-jwt-auth (using docker-compose.yml)

  • Make sure that AUTHENTICATION__ENABLED set to false in the .env in IMS API

  • The scigateway setting.json should look like this

{
   "plugins": [
     {
      "name": "inventory-managment-system",
      "src": "http://localhost:5001/main.js",
      "enable": false,
      "location": "main"
     }
   ],
   "auth-provider": null,
   "authUrl":""
}

Common commands

Here is a list of common commands used in development and a short description of what they do

  • yarn dev - start the development server that does hot reloading
  • yarn build - build the final bundled javascript
  • yarn test - run the tests and calculate the coverage
  • yarn lint - lint (and fix as much as possible) the typescript/javascript code
  • yarn e2e - run the end-to-end tests in a headless mode with mock data (useful for CI systems)
  • yarn e2e:interactive - run the end-to-end tests interactively with mock data (useful for debugging e2e tests)
  • yarn e2e:api - run the end-to-end tests in a headless mode using the api (useful for CI systems)
  • yarn e2e:interactive:api - run the end-to-end tests interactively using the api (useful for debugging e2e tests)

More commands can be found in package.json - specifically in the scripts section

Clone this wiki locally