From 3cdc979f7765c304815f500313dace6fb40420d9 Mon Sep 17 00:00:00 2001 From: u228298 Date: Tue, 10 Dec 2024 15:39:33 +0100 Subject: [PATCH 1/8] chore: add coding standards document Signed-off-by: u228298 --- CODING_STANDARDS.md | 61 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 CODING_STANDARDS.md diff --git a/CODING_STANDARDS.md b/CODING_STANDARDS.md new file mode 100644 index 0000000..e7132a4 --- /dev/null +++ b/CODING_STANDARDS.md @@ -0,0 +1,61 @@ +# Coding Standards + +This repository uses the IntelliJ formatter with customizations defined in the [codeStyles](.idea/codeStyles) +configuration. Ensure that you format the project before committing changes. + +- Add spaces after class definitions and before return statements if a method has more than three statements. +- Use spaces to group related blocks together (e.g., before `if` control flow statements). +- Follow these naming conventions: + - Use `camelCase` for methods. + - Use `UpperCamelCase` for classes. + - Use `ALL_UPPER_CASE` for static constants. + +Minimize boilerplate code by using Lombok to generate getters, setters, constructors, builders, or value classes. + +Do not use `Optional<>` for parameters. It is permitted for return types and internal object usage. Use method +overloading and omit the parameter instead. + +Example: + +```java + +@RequiredArgsConstructor +public class ExampleService { + + private static final int MAX_ATTEMPTS = 5; + + @Getter + private final int reqeustCount = 0; + + private final ExampleRepository repository; + + public Optional findById(String id) { + return repository.findById(id); + } +} +``` + +## Design + +- Restrict visibility as much as possible. Allow access from outside the package only when absolutely necessary. +- Program to interfaces, not implementations. +- Follow SOLID principles to structure your code (classes). +- Adhere to the DRY (Don't Repeat Yourself) principle. +- Avoid magic numbers or literals; use constants instead. + +## Documentation + +- Document only non-obvious public members using Javadoc (e.g., do not document simple getters or setters). +- Avoid comments in code except for complex logic or case structures. When comments are necessary, ensure they are clear + and concise. + +## Testing + +- Use JUnit 5 for testing. The use of AssertJ and Mockito is permitted. +- The Surefire plugin runs unit tests (`ExampleTest`), while the Maven Failsafe plugin runs integration tests ( + `ExampleIT`). +- Follow the naming conventions with the `Test` and `IT` postfixes. Use descriptive names for test cases: + - Use `should...`, `shouldNot...`, or `shouldThrow...`. + - The `_` character is allowed in test case names to differentiate cases. +- Use nested test classes to group thematically related test cases. +- For complex test setups, use the test builder pattern or introduce a test extension for reusability. From 62e1c2df1cdbbcf9da59736845e8f156974b4d9c Mon Sep 17 00:00:00 2001 From: u228298 Date: Tue, 10 Dec 2024 16:03:04 +0100 Subject: [PATCH 2/8] doc: add contributing guidelines Signed-off-by: u228298 --- CONTRIBUTING.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..81896a9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,111 @@ +# Contributing + +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](LICENSE) of the +repository and certify that you have all the rights to do so. + +## Code of Conduct + +This project and everyone participating in it is governed by the [Code of Conduct](CODE_OF_CONDUCT.md). +By participating, you are expected to uphold this code. + +## Found an Issue? + +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](https://github.com/SchweizerischeBundesbahnen/netzgrafik-editor-converter). Including an issue +reproduction 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 Pull Request with a fix. + +## Want a Feature? + +You can *request* a new feature by submitting an issue to +our [GitHub Repository](https://github.com/SchweizerischeBundesbahnen/netzgrafik-editor-converter). 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. + +## Submitting a Pull Request (PR) + +Before you submit your Pull Request (PR) consider the following guidelines: + +* Checkout a new branch: `feature/xxx` or `bugfix/xxx` +* Create your feature or patch, **including appropriate test cases**. +* Follow our [Coding Standards](CODING_STANDARDS.md). +* Run tests and ensure that all tests pass. +* Commit your changes using a descriptive commit message that follows our + [commit message conventions](#commit). +* Push your branch to GitHub. + +* 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](#commit). + +## Commit Message Guidelines + +This project uses [Conventional Commits](https://www.conventionalcommits.org/) to generate the changelog. + +### Commit Message Format + +``` +(): + + + +