Skip to content

Latest commit

 

History

History
64 lines (43 loc) · 5.68 KB

CONTRIBUTING.md

File metadata and controls

64 lines (43 loc) · 5.68 KB
Raw

Contributing

A note on backends

As you probably know by now, Hajk consists of three separate applications: Client UI, Admin UI and Backend. If this concept is new to you, please see the description here.

Prior to 2021, Backend implemented as a .NET application. In the spring of 2021, the Hajk NodeJS backend became available, finally making Hajk an OS-independent webGIS solution. At the time of writing (spring 2024), a new .NET Backend became available which intends to implement the same API specification as the NodeJS backend. However, given the current usage statistic, interoperability and developer's activity, the NodeJS backend remains the most widespread and well-tested solution.

Required tools

  • Latest LTS of NodeJS
  • Latest Git
  • Visual Studio (only for the optional .NET backend)

All apps reside inside the apps/ directory. The Client UI (client), Admin UI (admin) and NodeJS backend (backend) applications can be built and deployed on any OS supported by recent Git and Node versions (tested on macOS, Windows and Linux).

The .NET backend (backend-dotnet) component, requires Visual Studio for Windows.

User documentation

End-user documentation can be found in Hajk's Wiki. Writing user documentation is a very important way of contributing to the project and suits well for organizations that wish to contribute but lack coding capabilities.

Design guidelines

Hajk is built using Material Design components from the Material UI project. Make sure to familiarize yourself with all the available components. It is crucial for the user experience that the design principles are followed throughout the system.

Git workflow

Hajk strictly enforces the use of Git Feature Branch Workflow as described in this document.

Pre-requirements

Create an issue on GitHub. You will need the issue number to give your branch a good name in the steps that follow.

Steps in git

In short, developing a new feature, would look something like:

  1. Always fetch latest with git fetch.
  2. Make sure you are in the develop branch by git checkout develop.
  3. Make sure that you've merged all upstream changes in develop with git merge.
  4. Create a new branch and give it a name that relates to the issue you created on GitHub. E.g. if you created an issue called "Add a blue button" and it has issue number #1234, your branch should be called feature/1234-blue-button. You create this branch by running git checkout -b feature/1234-blue-button
  5. Don't forget to set upstream so that your newly created branch is pushed to GitHub: git push --set-upstream origin feature/1234-blue-button
  6. Code… :neckbeard:
  7. Regularly commit changes to your branch with git commit -S -m "A good comment, can be multiline.". (Note, the -S flag signs your commit, and signing commits is something you really should be doing.)
  8. Regularly push your changes upstream (to GitHub) with git push
  9. Regularly merge changes that other developers might be doing, from develop into your branch. That means that you will incorporate recent changes and your local branch will stay up-to-date with the latest developments. Please don't overlook it. This is a really important part. You can do it like this: git stash && git checkout develop && git fetch && git merge && git checkout feature/1234-blue-button && git merge develop && git stash apply. (If you feel comfortable enough with Git, there are of course shorter way of doing this, such as directly merging the upstream remote branch.)
  10. Describe your change with a log entry in the CHANGELOG.md. Select the subsection below the Unreleased section based on the type of issue: Added for feature, Fixed for any bug fixes, Changed for changes in existing functionality, Security in case of vulnerabilities. See further at the very end of CHANGELOG.md.
    Format your new row like:
    - area: Short explanation of what the change resolves/adds. [#issue-number](https://github.com/hajkmap/Hajk/issues/`issue-number`)
    • area: could be a specific feature in Hajk like Sketch, Print or Cookie or an app like Admin, Backend or Client or more generic like Core, Bug, Fix.
    • issue-number: The number of your Hajk issue.
  11. When you're done coding, go to GitHub and create a new pull request. Make sure that you want to merge your branch into develop.
  12. Hajk maintainers will get notified when you create the PR. They will review your PR and either accept and merge your branch (as well as delete it from the remote, as it's no longer needed) or (if the code isn't considered ready) request changes. After a successful merge you will still have a copy of your feature branch locally, but it can be safely removed by running git branch -d feature/1234-blue-button.

Code standard

Hajk uses ESLint and Prettier to enforce code formatting across the project.

🔥 Code that gets checked in must follow those rules. 🔥

The client and backend directories contain all necessary configuration files. The recommended way is to use an editor that has extensions for ESLint and Prettier installed. It is also highly recommended to make the editor run Prettier on each file save (i.e. in VSCode it can be controlled by the formatOnSave: true flag).

For a simple guide on setting up VSCode with ESLint, Prettier and some , see this presentation. (Swedish only)