diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..5b50106 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,37 @@ +--- +title: 'Bug: ' +labels: 'bug' +assignees: '' +--- + +<!-- + Thank you for helping us improve the project! + Please use this template to report bugs and help us understand the issue. +--> + +## Bug Report + +**Description** + +<!-- Please provide a clear and concise description of what the bug is. --> + +**Steps to Reproduce** + +<!-- + 1. Step one + 2. Step two + 3. Step three +--> + +**Expected behavior** + +<!-- What did you expect to happen? --> + +**Screenshots** + +<!-- If applicable, add screenshots to help explain your problem. --> + +--- +title: 'Bug: <Title>' +labels: 'bug' +assignees: '' \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..1bb11c7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,12 @@ +name: Issue Templates +description: Choose an issue template to use. +labels: + - bug + - enhancement +templates: + - name: Bug Report + path: bug_report.md + description: Create a report to help us fix a bug. + - name: Feature Request + path: feature_request.md + description: Suggest an idea for a new feature or enhancement. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..b9198e1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,34 @@ +--- +title: 'Feature: <Title>' +labels: 'enhancement' +assignees: '' +--- + +<!-- + Thank you for proposing a feature! + Please use this template to help us understand and evaluate your suggestion. +--> + +## Feature Request + +**Describe the solution you'd like** + +<!-- A clear and concise description of what you want to happen. --> + +**Describe alternatives you've considered** + +<!-- + A clear and concise description of any alternative solutions or features + you have considered. +--> + +**Additional context** + +<!-- + Add any other context about the feature request here. This could include screenshots, + diagrams, or additional explanations. +--> + +**Related Issues** + +<!-- If applicable, reference related issues (e.g., using `#issue_number`). --> diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..5c7a08b --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,44 @@ +--- +title: '<type>: <subject>' +labels: '' +assignees: '' +--- + +<!-- + Thank you for your contribution. Please use this template to help guide + you towards preparing a PR that fulfills our merge requirements. +--> + +## Pull Request + +**Description** + +<!-- Describe the changes your PR introduces here. --> + +**Issues** + +<!-- + Link related issues here, it's ok if this is empty but we do recommend that + you create issues before working on PRs, issues on internal trackers are + fine and need not be linked here. +--> + +**Checklist** + +<!-- + Take care of the default items before marking your PR as ready for review, + be prepared to add more items. +--> + +* [ ] This PR contains a description of the changes I'm making and its title follows the Conventional Commit format ( + e.g., `feat:`, `fix:`) +* [ ] I've read + the [Contribution Guidelines](https://github.com/SchweizerischeBundesbahnen/netzgrafik-editor-converter/blob/main/CONTRIBUTING.md) +* [ ] I've added tests for changes or features I've introduced +* [ ] I documented any high-level concepts I'm introducing in `docs/` +* [ ] CI is currently green and this is ready for review + +<!-- + Please open PRs as Draft while you make CI green and/or finalise + documentation. +--> \ No newline at end of file diff --git a/.github/workflows/maven-ci.yml b/.github/workflows/maven-ci.yml index 45ab54a..b4edaf3 100644 --- a/.github/workflows/maven-ci.yml +++ b/.github/workflows/maven-ci.yml @@ -2,10 +2,11 @@ name: Maven CI on: push: - branches: [ "main" ] + branches: + - main pull_request: - branches: [ "main" ] - + branches: + - main jobs: build: runs-on: ubuntu-latest @@ -17,7 +18,7 @@ jobs: with: java-version: '21' distribution: 'temurin' - cache: maven + cache: 'maven' - name: Build with Maven run: mvn -B verify --file pom.xml diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml new file mode 100644 index 0000000..4f0261d --- /dev/null +++ b/.github/workflows/release-please.yml @@ -0,0 +1,39 @@ +name: Release Please + +on: + push: + branches: + - main + +permissions: + contents: write + packages: write + pull-requests: write + +jobs: + release-please: + runs-on: ubuntu-latest + outputs: + release_created: ${{ steps.release.outputs.release_created }} + steps: + - uses: googleapis/release-please-action@v4 + id: release + with: + release-type: maven + + release: + needs: release-please + if: ${{ needs.release-please.outputs.release_created }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-java@v4 + with: + java-version: '21' + distribution: 'temurin' + cache: 'maven' + + - name: Publish + run: mvn deploy -s $GITHUB_WORKSPACE/settings.xml + env: + GITHUB_TOKEN: ${{ github.token }} \ No newline at end of file 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<Example> 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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2982c6d --- /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](https://github.com/SchweizerischeBundesbahnen/netzgrafik-editor-converter/tree/main?tab=coc-ov-file). +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 Guidelines. +* Push your branch to GitHub. + +* In GitHub, send a pull request to `SchweizerischeBundesbahnen/netzgrafik-editor-converter:main`. + The PR title and message should as well conform to the Commit Message Guidelines. + +## Commit Message Guidelines + +This project uses [Conventional Commits](https://www.conventionalcommits.org/) to generate the changelog. + +### Commit Message Format + +``` +<type>(<optional scope>): <subject> +<BLANK LINE> +<body> +<BLANK LINE> +<footer> +``` + +Any line of the commit message cannot be longer 100 characters! This allows the message to be easier +to read on GitHub as well as in various git tools. + +### Type + +Must be one of the following: + +* **feat**: A new feature +* **fix**: A bug fix +* **docs**: Documentation only changes +* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semicolons, ...) +* **refactor**: A code change that neither fixes a bug nor adds a feature +* **perf**: A code change that improves performance +* **test**: Adding missing tests or correcting existing tests +* **build**: Changes that affect the build system, CI configuration or external dependencies (example scopes: + maven, ci, ...) +* **chore**: Other changes that don't modify `src` or `test` files + +### Scope + +The scope could be anything specifying place of the commit change. For example `converter`, `gtfs`, etc. + +### Subject + +The subject contains succinct description of the change: + +* use the imperative, present tense: "change" not "changed" nor "changes" +* don't capitalize first letter +* no dot (.) at the end + +### Body + +Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes". +The body should include the motivation for the change and contrast this with previous behavior. + +### Footer + +The footer should contain any information about **Breaking Changes** and is also the place to +reference GitHub issues that this commit **Closes**. + +**Breaking Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines. +The rest of the commit message is then used for this. + +## Attribution + +This CONTRIBUTING guideline is adapted from +the [sbb-design-systems/sbb-angular](https://github.com/sbb-design-systems/sbb-angular) diff --git a/README.md b/README.md index bd0b217..9a1b3b0 100644 --- a/README.md +++ b/README.md @@ -131,6 +131,15 @@ The class diagram outlines core classes and their relationships: ![Class diagram](docs/uml/class-diagram.svg) +## Contributing + +This repository includes [Contribution Guidelines](CONTRIBUTING.md) that outline how to contribute to the project, +including how to submit bug reports, feature requests, and pull requests. +The [Coding Standards](CODING_STANDARDS.md) outline best practices and rules to follow when coding. +Details on releasing are described in the [Release](RELEASE.md) document. + +## Continuous Integration + ## License This project is licensed under GNU [GPL-3.0](LICENSE). diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 0000000..d5f6187 --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,16 @@ +# Release + +Releases in this repository are managed using [release-please](https://github.com/googleapis/release-please), an +automated GitHub Action that updates project versions and generates release notes based on commit messages. With Maven +configured in the project, `release-please` identifies version changes, updates `pom.xml`, and ensures new versions are +pushed to GitHub Packages. + +## How It Works + +1. **Commit-based Version Bumps**: Commit messages trigger version increments (`feat:`, `fix:`, etc.) based + on [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). +2. **Release Creation**: `release-please` runs to create a new release and drafts the corresponding release notes. +3. **Maven Deployment**: A second job builds the project and deploys artifacts to GitHub Packages using Maven. + +For detailed configuration and usage, refer to +the [release-please Java and Maven Strategies](https://github.com/googleapis/release-please/blob/main/docs/java.md). diff --git a/pom.xml b/pom.xml index edd10d6..1ad163a 100644 --- a/pom.xml +++ b/pom.xml @@ -10,7 +10,7 @@ </parent> <groupId>ch.sbb.pfi.netzgrafikeditor</groupId> <artifactId>netzgrafik-editor-converter</artifactId> - <version>1.0.0-SNAPSHOT</version> + <version>1.0.0</version> <name>netzgrafik-editor-converter</name> <description>Converter to expand network graphics from the Netzgrafik-Editor into timetables for the entire service day in different formats @@ -20,6 +20,14 @@ <java.version>21</java.version> </properties> + <distributionManagement> + <repository> + <id>github</id> + <name>GitHub Packages</name> + <url>https://maven.pkg.github.com/SchweizerischeBundesbahnen/netzgrafik-editor-converter</url> + </repository> + </distributionManagement> + <licenses> <license> <name>GPL-3.0</name>