Skip to content
This repository has been archived by the owner on Apr 9, 2024. It is now read-only.

How to contribute

Jump to bottom
Gard Njåtun Krøyer edited this page May 29, 2019 · 23 revisions

Contributing with Code

We are constantly looking for engaged contributors to help us with the development of our community based surveillance platform.

Check out the issues labeled good first issue, they are good candidates to pick up if you are in the code for the first time.

Build and Run

Follow the steps below in order to clone, build and run the project.

Getting the sources

For windows computers, the command below must be run as administrator in command-line:

git config --system core.longpaths true

Then run the following command to get the resources:

git clone https://github.com/IFRCGo/cbs.git

Prerequisites

Understanding the project structure

CBS is built using the Domain Driven Design pattern and has been divided into 5 bounded contexts (or projects/modules). Each bounded context is completely isolated from the others, with it's own frontend and backend code. This means that when you work in a specific bounded context, you only need to understand the internals of that bounded context and can ignore the others.

The communication between the bounded contexts is event-driven. This means that the module you are working in will process incoming events from other modules and emit events for other modules to process. For new contributors who have yet not worked with event-driven architectures this way of communicating might take some getting used to, but please do not introduce any APIs for communicating between bounded contexts.

Overview of bounded contexts

Bounded Context Description Issue label Bounded Context Folder
Reporting Registering "data collectors", parsing and validation of incoming text messages from data collectors. «Data verifiers» and «data owners» can view, search, filter and export «case reports» and provide feedback to the Reporting Reporting
Admin Administrative features such as managing health risks, projects, feedback messages and much more. Admin Admin
Alerts All «health risks» have a set «threshold». If the «threshold» is exceeded, an «alert» will be created to notify the Red Cross and other interested parties. Alerts Alerts
Analytics Transforming data into actionable intelligence with reporting and dashboards. Analytics Analytics
Notification Gateway Notification gateway receiving and sending text messages and emails. SMS Proxy Sms

Running the code for a bounded context

Each bounded context has its own subfolder in the Source folder, containing a .sln file. The folder name per bounded context can be found in the table above.

Everything you need to build and run the bounded context can be found within the specified folder for said bounded context. For example, everything you need to build and run the "Reporting" bounded context, can be found in the Reporting folder under Source.

For simplicity, we have also added a generalized guide for running a bounded context below. This step-by-step guide applies to all bounded contexts except Analytics. To run Analytics see here

In all steps below, replace {Bounded Context Folder} with the folder of the bounded context you would like to run.

Step 1: Run MongoDB in a Docker container

docker run -p 27017:27017 mongo

Step 2: Build and run the .NET Core backend on your local machine

(Active path: cbs\Source\{Bounded Context Folder})

Download nuget dependencies

dotnet restore

Build

dotnet build

(Active path: cbs\Source\{Bounded Context Folder}\Core)

Run locally

dotnet run

Open browser at address http://localhost:5000/swagger to access Swagger.

Step 3: Building and running the Node.js/Angular.js frontend on your local machine

(Active path: cbs/Source/{Bounded Context Folder}/Web)

Restore dependencies

npm install

Build and host locally

npm start

Open http://localhost:portnumber/ in your browser to access the UI. (see console for correct port number)

If you experience any issues it might be worth your while to check out https://github.com/IFRCGo/cbs/wiki/Known-local-error-messages-with-solutions

Step 4: (Optional) Populating the database with test data

The following bounded contexts have support for populating the database with test data to get you going. Each links to the documentation for how to do this:

Running Analytics

The analytics bounded context is coded differently than the others. Here the backend project is in the Web/ folder and the frontend in the Web.Frontend folder. To run it:

Go to Source/Analytics/Web/ and install all dependencies

dotnet restore

Run the backend

dotnet run

Go to Source/Analytics/Web.Frontend/ and install dependencies

npm install

Run the frontend

npm start

To populate test data go to http://localhost:5000/swagger and run the TestDataGenerator.

Backlog

Each bounded context has its own backlog that can be found on the GitHub project page.
For example: The backlog for the "Reporting" bounded context can be found on the "Reporting" project page.

Any issue labeled "good first issue" will also have a label referencing the bounded context it belongs to so that you will be able to find the source code for the bounded context as explained above.

Next steps

  1. Find an issue you want to work on. Issues labeled "good first issues" are issues that should be relatively easy to get started on without too much background information.
  2. Create a fork. In order to contribute to this project, you will need to fork this repository.
  3. Create a branch, make changes and test them. All commits must be related to an issue by adding a #{number of issue} to the comment.
  4. Synchronize your fork. Keep your fork synchronized with the CBS repository to avoid conflicts, as described here.
  5. Create a pull request. Once your changes are ready, create a pull request and reference the issues you have worked on.

.

Contributing

Clone this wiki locally