-
Notifications
You must be signed in to change notification settings - Fork 4
Contributor Guidelines: Getting started
This document describes guidelines and rules that have to be considered and should be followed for all our projects. These points help us to maintain all our projects and to ensure every application runs as expected on our servers.
In addition, it describes how we work together and how we would like you to structure and organize your work. Like this we can make sure to keep an overview of all running projects and track progress.
In this section we will guide you through our desired collaboration workflow. This should help you to understand how to organize the work and how to assign the tasks to us.
First, we organize our repositories with two main branches: the main (development for old projects) and the prod branch.
The prod branch represents the currently running version of the application in production. All the code that gets merged into prod will be automatically deployed to production. However, you don’t have to take this branch into consideration at all, because all pull requests must have the main branch as destination and not the prod branch.
The main branch on the other hand represents the currently running version of the application on the test environment. Also the code of this branch gets automatically deployed to the test environment. And this branch should also be the destination branch of all our pull requests.
Second, all the pull requests should follow if possible these rules:
-
Start your work with a Pull request Mark it as draft or put the prefix “wip” for work in progress into the title
-
Only include one feature per pull request Don’t include too many features into one pull request. Ideally, just one feature/task should be part of one pull request.
-
Only touch relevant files If some files don’t have to do with the pull request, then please don’t change them.
-
Make sure your code is clean Clean up the code before committing. This includes for example adjusting the formatting and removing all debug logs.
-
Check the project CI Make sure your commits are passing the CI and inspect all issues the CI is reporting.
-
Resolve merge conflicts Provide a pull request without merge conflicts, monitor the pull request by yourself.
-
Submit a running solution The tests in the pull request must pass and the application should not break. Monitor and fix eventual CI alerts and errors by yourself.
A more in depth explanation including screenshots can be found here: https://docs.opendatahub.bz.it/en/latest/guidelines/contributors.html#create-a-pull-request)
Use your Kanban to signal project progress. Monitor all Kanban Issues and move them through the defined lanes (Backlog, To Estimate, To Do, In Progress, To Review, Done). (NOI only) means that Moving an issue to this lane can be done only by NOI.
-
Backlog: Issues that have not been started and assigned yet
-
To Estimate (NOI only): Big Issues where we need a proper effort estimation
-
To Do (NOI only): Assigned Issues that should be solved
-
In Progress: signal us that you are working on this issue
-
To Review: Issue that has been done (ex. with associated PR) and needs to be reviewed by NOI
-
Done (NOI only): Reviewed Issues by NOI where all work is done
If you find your own Issues or Questions open an issue and put it into the Backlog.
Start your project from an existing boilerplate. We already prepared a couple of different bootstrapped projects, so that you don’t have to set up everything from scratch.
In addition, everything is already prepared the way we like it including for example readme.md, configuration, logging, deployment and much more.
https://github.com/orgs/noi-techpark/repositories?q=boilerplate&type=&language=&sort=
We try to not use too many different technologies, so that we are able to maintain the projects even in the future. That’s why we would ask you to pick one of our core languages and frameworks
- Backend: Java with Spring Boot or .Net Core C#
- Frontend: HTML/CSS/Javascript with Vue/Nuxt.js
The readme.md files should be a very well written document that first should contain a short description about the project, so that other developers quickly understand the scope of it. In addition, all necessary information to set up the document locally and on a server should be given.
If there are some special points regarding the project, they should be documented as well.
This helps us to be able to remember all necessary steps also in the future and to allow other people to check out the open source projects and make use of them.
The boilerplates already contain a predefined readme.md file, that follows our desired structure.
All the configuration must happen through environment variables. This is important so we are able to create different environments like test and production.
Important! Don’t commit passwords, keys and other secret information to the source code.
Example:
- Spring Boot: https://github.com/noi-techpark/davinci-innovation-scoreboard-api
- Nuxt.js: https://github.com/noi-techpark/davinci-innovation-scoreboard-web
Use a PostgreSQL database. When we deploy an application, then we create a database on a hosted database server and provide the credentials to the application using environment variables.
To also keep track of the database schema, it is important that the application also includes migrations that are or can be executed on startup.
Important! Don’t use an SQLite database.
Don’t write files to the local files system. On our infrastructure we deploy the application inside a Docker environment, and so files will not be persisted between deployments.
Use a service like S3 for storing files.
All logs should be written to the standard output (STDOUT) in JSON format (one line per log). This is the default behavior when using Docker containers. Most of the common containers are already configured to function like this. In addition, every log line must include a “@timestamp” field with the current log time. For local development it should be possible to use plain text for logging.
{
"@timestamp":"2021-07-18T16:56:43.938Z",
"message":"No mapping for GET /robots.txt",
"level":"WARN",
"level_value":30000
}Important! Debug logs must be disabled on test and production environments.
In order to allow users to sign in to different applications with always the same credentials, we created a centralized authentication server. This central authentication server helps us manage access in one single place.
In addition, the central authentication server supports the most known and used authentication techniques like OpenID and OAuth 2.0.
Please don’t implement the authentication layer by yourself, but rather integrate your application to our central solution.
Examples: https://github.com/noi-techpark/authentication-server-examples
Or you can also take a look at these projects:
This wiki contains additional information about the Open Data Hub alongside the Open Data Hub - Official Documentation 🔗 .