Contributing to byor-voting-server

First of all, thanks for taking the time to contribute to the project!

The following is a set of guidelines, not rules, for contributing. Feel free to propose changes to this document in a pull request.

Code of Conduct

This project and everyone participating in it is governed by the Covenant Code of Conduct. By participating, you are expected to uphold this code.

Support from the community

You can find out more about how to get in touch with the community in SUPPORT.md

What should I know before I get started?

The BYOR-VotingApp is a companion app to build-your-own-radar project (aka BYOR).

BYOR

Is a library that generates an interactive radar, inspired by ThoughtWorks Technology Radar.

The radar creation exercise invites you to have a conversation across all organizational levels and review your entire technology portfolio. This enables you to:

Objectively assess what's working, and what isn't
Pollinate innovation across teams and experiment accordingly
Balance the risk in your technology portfolio
Work out what kind of technology organization you want to be
Set a path for future success

You can generate the radar:

running locally the BYOR project
submitting your blips in Google Sheet or csv format to the BUILD YOUR OWN RADAR page
running the BYOR-VotingApp, collecting blips and generating the radar on the fly

BYOR-VotingApp

The BYOR-VotingApp helps you to collect blips and to enable conversations during the radar creation exercise.

The BYOR-VotingApp is a SPA (single page application) built with Angular 7 that interacts with a nodejs RESTful backend. Data is saved in a MongoDB database.

You can use your MongoDb of choice or provision it through the scripts provided in the infrastructure project.

Github repositories

There is a github respository for the front-end, one for the back-end, plus one for setting up the necessary infrastructure on Kubernetes or AWS lambda.

How Can I Contribute?

Reporting Security Bugs

Security bugs should not be reported as issues. You can find out more about how to report them correctly in SECURITY.md

Reporting Bugs

When you are creating a bug report, please include as many details as possible. Fill out the required template, the information it asks for helps us resolve issues faster.

Note: If you find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.

Before Submitting A Bug Report

Determine which repository the problem should be reported in.
Perform a search in issues to see if the problem has already been reported. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one.

How Do I Submit A (Good) Bug Report?

Bugs are tracked as GitHub issues. After you've determined which repository your bug is related to, create an issue on that repository and provide the following information by filling in the template:

Use a clear and descriptive title for the issue to identify the problem.
Describe the exact steps which reproduce the problem in as many details as possible.
Don't just say what you did, but explain how you did it.
Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use Markdown code blocks.
Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
Explain which behavior you expected to see instead and why.
If the problem wasn't triggered by a specific action, describe what you were doing before the problem happened and share more information using the guidelines below.

Provide more context by answering these questions:

Did the problem start happening recently (e.g. after updating to a new version) or was this always a problem?
If the problem started happening recently, can you reproduce the problem in an older version? What's the most recent version in which the problem doesn't happen?
Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.

Suggesting Enhancements

When you are creating an enhancement suggestion, please include as many details as possible. Fill in the template, including the steps that you imagine you would take if the feature you're requesting existed.

Before Submitting An Enhancement Suggestion

Determine which repository the enhancement should be suggested in.
Perform a search in issues to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.

How Do I Submit A (Good) Enhancement Suggestion?

Enhancement suggestions are tracked as GitHub issues. After you've determined which repository your enhancement suggestion is related to, create an issue on that repository and provide the following information:

Use a clear and descriptive title for the issue to identify the suggestion.
Provide a step-by-step description of the suggested enhancement in as many details as possible.
Describe the current behavior and explain which behavior you expected to see instead and why.

Pull Requests

The process described here has several goals:

Maintain BYOR-VotingApp's quality
Fix problems that are important to users
Engage the community in working toward the best possible BYOR-VotingApp
Enable a sustainable system for BYOR-VotingApp's maintainers to review contributions

Please follow these steps to have your contribution considered by the maintainers:

Follow all instructions in the template
Follow the guidelines
After you submit your pull request, verify that all status checks are passing
What if the status checks are failing?
If a status check is failing, and you believe that the failure is unrelated to your change, please leave a comment on the pull request explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. If we conclude that the failure was a false positive, then we will open an issue to track that problem with our status check suite.

While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted.

Note: consider that the Continuous Integration logic runs lint checks and uses the prettier module - if you use VSCode it is recommended to install the "Prettier - Code formatter" extension to avoid lint errors.

Guidelines

Git Commit Checks

Secrets disclosure prevention

A git pre-commit hook is automatically installed in the local repository via Husky configuration.

This pre-commit hook will run before any commit to scan the project files with Talisman, looking for things that seem suspicious, such as authorization tokens and private keys.

In case there is any suspect of being about to commit some secrets, the commit will be aborted and a detailed report of the suspicious contents will be printed out on the console. Please refer to Talisman offical documentation for more details about secrets disclosure prevention.

Git Commit Messages

Commit are handled with a precommit hook that enforces the commit message structure via Commitizen.

The adopted commit message structure is the AngularJS's commit message convention, also known as conventional-changelog.

Release Versioning

Releases are automated with the semantic-release script that gets executed for any set of commits successfully validated by CI/CD pipelines after a change is pushed to the master branch. The semantic-release script takes care of:

setting the right application version number (based on commits' history and semantic versioning conventions) in package.json and package-lock.json files
updating the CHANGELOG.md file based on commits' history
pushing a new tag/release to the GitHub repository

Typescript Styleguide

Typescript styleguide is defined as a set of lint rules.

You can check if your code conforms to them by running:

make lint

If not executed in CI mode, the above command will prompt the user for trying to automatically fix linting errors.

Testing

Unit tests: make unit_tests
Integration tests (run with byor-voting-server+mongo): make integration_tests

If not executed in CI mode, the above commands will prompt the user for executing tests in watch mode.

For VSCode users: the test execution (both unit and integration) can be debugged with the debug configuration named Test: launch current file: open a test file in the VSCode editor and run debug Test: launch current file. (TODO there is one open issue with this configuration: the breakpoints added from VSCode go to the wrong line)

DB Migrations

Any kind of changes to the data, both DDL (eg: indexes creation) and DML (eg: insert/update of golden data), should be manage via [node-migrate](https://github.com/tj/node-migrate). Use the following make command to interactively create a new migration:

make migration_create

Caveats:

Migration names can contain only alphanumeric lowercase characters and hypens
node-migrate automatically prepends the creation timestamp to any newly generated migration
After generating a migration with make migration_create, it's necessary to implement the migration's logic inside its up method
Existing migrations should never be deleted or modified, create new migrations to extend or override the effects of existing migrations

Run the continuous integration on local

You can run the CI logic on local via the command:

make ci_all

Build the application for Production

To build the app for production use:

make build

If no environment variable named BACKEND_SERVICE_URL is existing in the current shell, the above command will interactively ask the user for the backend service URL he/she wants to target.

The build artifacts will be stored in the dist/ directory.

Build the docker image

docker build -t byor-voting-server:latest .

HOWTOs

Database connection configuration

For any kind of deployment, the following environment variables should be properly valued:

MONGO_URI: the mongo connection string (with username and password, if any) for normal read/write operations
MONGO_DB_NAME: the mongo database name

Connection to bundled MongoDB

It's possible to connect to the MongoDB bundled with the local container with any external client, like MongoDB Compass, using these parameters:

Hostname: localhost
Port: 27001
Authentication: None

Running the application locally in watch mode

Prerequisites

GNU Bash
GNU Make
Docker

The commands to build, test and deploy the application are managed via make, which acts as a facility for executing npm scripts inside a docker container. Execute the following command from the root directory of the project to get the complete list of available make commands:

make

First run

To run the backend locally the first time you will need to build it with:

make install

This may take a few minutes. A MongoDB will be bundled in the docker container.

Running server in watch mode

To start the local dev server in watch mode (this also runs pending database migrations, if any):

make dev_server_start

Stop the local dev server:

make dev_server_stop

Clean up the local application (this will also remove all your local application data, if any):

make dev_clean_up

Running the application from VSCode

create a .env file in the root of the project where to define the required environment variables - in case of a local mongodb server this file could be
```
MONGO_URI=mongodb://mylocalhosthost:27017/
MONGO_DB_NAME=byorDev
```
go to the debug view of VSCode, select "Launch Dev Server" configuration and launch the debugger
when on the Debug Console appears the message -->[INFO] Listening on port 3000 the server is running
you can now place breakpoints and debug interactively

Debugging server from VSCode

For VSCode users: the local dev server can be debugged with the debug configuration named D�ev server: attach. (:warning: TODO there is one open issue with this configuration: the breakpoints added from VSCode go to the wrong line)

Manage application's container

Any arbitrary command can be executed in the context of the application's container via the following command:

make execute_command

If no environment variable named command is existing in the current shell, the above command will prompt the user for the command to be executed.

To avoid interactive command request, run:

command="echo 'replace this echo with real command'" make execute_command

Running the application from production-grade docker image

execute:

export MONGO_URI='mongo-uri-here'
export MONGO_DB_NAME='mongo-db-name-here'
export EXPOSED_BACKEND_PORT='exposed-backend-port-here'
docker run -it --rm -p ${EXPOSED_BACKEND_PORT}:3000 -e MONGO_URI -e MONGO_DB_NAME byor-voting-server:latest

Import technologies from a Google Spreadsheet or csv file

The import will override all the existing technologies in the target database.

The spreadsheet must be a public accessible Google Sheet and it must have a column for each of the following attributes: name, quadrant, isNew.

All the technologies will be imported as new for now.

To interactively run the import:

make import_technologies_from_gsheet

You'll be prompted for the following inputs:

MongoDB URI (mandatory): the MongoDB connection string (with username and password, if any) for normal read/write operations (eg: mongodb+srv://username:password@hostname/)
MongoDB name (mandatory): the mongo database name
spreadsheet id (mandatory): the id of the public Google Sheet to import technologies from
sheet number (optional, default value = 1): the index of the sheet to import from
name column (optional, default value = name): the name of the column that maps the name attribute
quadrant column (optional, default value = quadrant): the name of the column that maps the quadrant attribute
isNew column (optional, default value = isNew): tells if it has been recently added to the list

or

make import_technologies_from_csv