How to contribute

Cathinka Walberg edited this page Jan 16, 2019 · 13 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

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

Note: Historically, we have had two bounded contexts called User Management and Volunteer Reporting. We are in the process of merging these into one and renaming the merged bounded context to "Reporting".

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 & Volunteer Reporting VolunteerReporting
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 VolunteerReporting 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.

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.Angular)

Restore dependencies

npm install

Build and host locally

npm start

Open http://localhost:4200/ in your browser to access the UI.

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

To populate the database with test data, go to http://localhost:5000/swagger and use the TestDataGenerator API. This will retrieve test data from the /Web/TestData folder and add it to the database.

Backlog

Each bounded context has its own backlog that can be found on the GitHub project page.
For example: The backlog for the "Volunteer Reporting" bounded context can be found on the "Volunteer 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.
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.