We appreciate all kinds of contributions. The following is a set of guidelines for contributing to this repository on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
By submitting a contribution to this repository you agree that you do this under the license of the repository and certify that you have all the rights to do so.
What should I know before I get started?
- Issues and Bugs
- Feature Requests
- Pull Requests Guidelines
- Your First Code Contribution
- Coding Rules
- Commit Message Guidelines
This project and everyone participating in it is governed by the Code of Conduct. By participating, you are expected to uphold this code.
Please ask the questions in the discussions page.
This project is based on Angular and uses the SBB Angular Library.
For getting a development environment up and running you either need to have Node installed locally or you can use the provided docker-compose.yml file.
The Angular frontend depends on the backed in the netzgrafik-editor-backend, so you also need to start the backend components.
Have a look at DATA_MODEL.md
If you find a bug in the source code or a mistake in the documentation, you can help us by submitting an issue to our GitHub Repository. Including an issue reproduction (via StackBlitz, JsBin, Plunkr, etc.) is the absolute best way to help the team quickly diagnose the problem. Screenshots are also helpful.
You can help the team even more and submit a Pull Request with a fix.
You can request a new feature by submitting an issue to our GitHub Repository. If you would like to implement a new feature, please submit an issue with a proposal for your work first, to be sure that we can use it. Please consider what kind of change it is:
- For a Major Feature, first open an issue and outline your proposal so that it can be discussed. This will also allow us to better coordinate our efforts, prevent duplication of work, and help you to craft the change so that it is successfully accepted into the project.
- Small Features can be crafted and directly submitted as a Pull Request.
If your issue appears to be a bug, and hasn't been reported, open a new issue. Providing the following information will increase the chances of your issue being dealt with quickly:
- Overview of the Issue - if an error is being thrown a non-minified stack trace helps
- Toolchain and Environment Details - which versions of libraries, toolchain, platform etc
- Motivation for or Use Case - explain what are you trying to do and why the current behavior is a bug for you
- Browsers and Operating System - is this a problem with all browsers?
- Reproduce the Error - provide a live example (using StackBlitz or similar) or a unambiguous set of steps
- Screenshots - myybe screenshots can help the team triage issues far more quickly than a text description.
- Related Issues - has a similar issue been reported before?
- Suggest a Fix - if you can't fix the bug yourself, perhaps you can point to what might be causing the problem (line of code or commit)
You can file new issues by providing the above information here.
To be able to quickly address issues, we strive to organize issues with types and labels.
Types (coming from OpenRailAssociation organization):
| Type | Corresponding issues |
|---|---|
Bug |
Bugs (bug:{severity} label) (Issue template is "Bug") |
Enabler |
Enablers: - technical - data model evolution |
Feature |
- Feature proposal (= design document): problem with the solution to implement (Issue template is "Design Document") - Feature request: problem to solve, mostly from external users (Issue template is "Feature Request") - Enhancement of an existing feature |
Refacto |
- Technical chores (dependency issues, ...) - Code quality - Technical enhancements |
Task |
Subdivision of a larger Feature |
Labels (coming from OpenRailAssociation/netzgrafik-editor-frontend (see already existing NGE's labels and OSRD's labels):
| Label | Description | Examples |
|---|---|---|
area:view |
Actual components ("visual" stuff) | - src/app/view/*- src/app/perlenkette/perlenkette-section |
area:services |
Services, helpers, utils and i18n ("logical" stuff) | - src/app/services/*- src/app/utils/*- src/app/perlenkette/service |
area:data-model |
Data models and structures | - src/app/data-structures/*- src/app/models/*- src/app/perlenkette/model |
area:ci |
GitHub actions | - .github/* |
bug:minor |
The feature is not compromised (e.g. slight css bug) |
# trainrun-and-section-tab component closing issue #739 |
bug:major |
The feature is not fully compromised and requires the user to "hack" to get the full feature (e.g. having to close manually something or reload the window) | # One-way card selection order #658 |
bug:critical |
The feature is fully compromised (e.g. white screen or a view that does not open at all) | # O/D Matrix - overlays nodes with the same name. #489 |
design-document |
This is the main document that a developer uses to implement a feature, everything needed should be part of it ("Description", "Mock-ups", "Acceptance Criteria", "Implementation Plan" and "Definition of Ready") | # Manually re-order trainruns in nodes #636 |
feature-request |
A request of a new feature of the enhancement of an existing one. | Asymmetric Times in Timetable Concepts #242 |
dependencies |
Dependencies (from Dependabot mostly) | |
documentation |
About documentation | |
experimental |
For mad scientists | |
help-wanted |
Ask for help on a matter | |
postponed |
Postponed | |
ux/ui |
User experience, user interface (design) | |
good-first-issue |
Issue that does not need large business or technical context | |
from-user |
Issue from user |
Because each release is linked on a milestone, issues need to be tagged as a milestone, if relevant, to be able to quickly see what's prior in the issues list.
Issue that need to be tagged as a milestone:
- Features that directly impact the users
- As well as Design Documents
- Evolutions of the data model
- Large refactoring issues
- Critical bug fixes
- Major bug fixes
Issues that do not need to be tagged as a milestone:
- Technical issues
- Refactoring issues
- Minor bug fixes
- Pull Requests (since a Pull Request should always reference an opened issue (using "Ref #issue" or "Close #issue"))
Before you submit your Pull Request (PR) consider the following guidelines:
-
Make your changes in a new git branch:
git checkout -b my-fix-branch main
-
Create your patch, including appropriate test cases.
-
Follow our Coding Rules.
-
Test your changes with our supported browsers and screen readers.
-
Run tests and ensure that all tests pass.
-
Commit your changes using a descriptive commit message that follows our commit message conventions. Adherence to these conventions is necessary because release notes are automatically generated from these messages.
git commit -a
Note: the optional commit
-acommand line option will automatically "add" and "rm" edited files. -
Push your branch to GitHub:
git push my-fork my-fix-branch
-
In GitHub, send a pull request to
sbb-your-project:main. The PR title and message should as well conform to the commit message conventions.
To ensure consistency throughout the source code, keep these rules in mind as you are working:
- All features or bug fixes must be tested by one or more specs (unit-tests).
- All public API methods must be documented.
- Also see CODING_STANDARDS
This project uses Conventional Commits to generate the changelog. As an example, please refer to: https://github.com/sbb-design-systems/sbb-angular
The project is using Release please
A configuration file ensures the commits are following the format, in particular that the commit message prefix is one of the following:
feat:: a new user-visible featurefix:: a bug fix, or preventing a future bugdocs:: documentation only changesstyle:: changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)refactor:: a code change that neither fixes a bug nor adds a feature (but could prepare the work for a following commit)perf:: a code change that improves performancetest:: adding missing tests or correcting existing testsbuild:: changes that affect the build system or external dependenciesci:: changes to the CI configuration files and scriptschore:: dependencies update (mostly from dependabot and release-please)
Note: feat!:, or fix!:, refactor!:, etc., which represent a breaking change (indicated by the !).
Unsure where to begin contributing to Atom? You can start by looking through these beginner and help-wanted issues:
- [Beginner issues][beginner] - issues which should only require a few lines of code, and a test or two.
- [Help wanted issues][help-wanted] - issues which should be a bit more involved than
beginnerissues.
This CONTRIBUTING guideline is adapted from the sbb-design-systems/sbb-angular