document how to update versions and dependencies

aas_core3-config.cmake

@@ -7,6 +7,7 @@ include(${SELF_DIR}/aas_core3.cmake)
 
 include(CMakeFindDependencyMacro)
 
-find_dependency(tl-optional 1 REQUIRED)
 find_dependency(nlohmann_json 3 REQUIRED)
-find_dependency(EXPAT 2 REQUIRED)
+find_dependency(expat 2 REQUIRED)
+find_dependency(tl-optional 1 REQUIRED)
+find_dependency(tl-expected 1 REQUIRED)

doc/changelog.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.0.1-alpha.1 (2024-01-17)
+
+This is the initial alpha release, ready for first reviews.

doc/contributing.md

@@ -0,0 +1,81 @@
+# Contributing Guidelines
+
+## Issues
+
+Please report bugs or feature requests by [creating GitHub issues].
+
+[creating GitHub issues]: https://github.com/aas-core-works/aas-core3.0-cpp/issues/new/choose
+
+## In Code
+
+If you want to contribute in code, pull requests are welcome!
+
+Please do [create a new issue] before you dive into coding.
+It can well be that we already started working on the feature, or that there are upstream or downstream complexities involved which you might not be aware of.
+
+[create a new issue]: https://github.com/aas-core-works/aas-core3.0-cpp/issues/new/choose
+
+### SDK Code Generation
+
+The biggest part of the code has been automatically generated by [aas-core-codegen].
+It probably makes most sense to change the generator rather than add new functionality.
+However, this needs to be decided on a case-by-case basis.
+
+[aas-core-codegen]: https://github.com/aas-core-works/aas-core-codegen
+
+## Pull Requests
+
+**Feature branches**.
+We develop using the feature branches, see [this section of the Git book].
+
+[this section of the Git book]: https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows
+
+If you are a member of the development team, create a feature branch directly within the repository.
+
+Otherwise, if you are a non-member contributor, fork the repository and create the feature branch in your forked repository. See [this GitHub tuturial] for more guidance.
+
+[this GitHub tutorial]: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork
+
+**Branch Prefix**.
+Please prefix the branch with your Github user name (*e.g.,* `mristin/Add-some-feature`).
+
+### Commit Messages
+
+The commit messages follow the guidelines from https://chris.beams.io/posts/git-commit:
+
+* Separate subject from body with a blank line,
+* Limit the subject line to 50 characters,
+* Capitalize the subject line,
+* Do not end the subject line with a period,
+* Use the imperative mood in the subject line,
+* Wrap the body at 72 characters, and
+* Use the body to explain *what* and *why* (instead of *how*).
+
+## Version Bumps
+
+When you want to update the version, please undertake the following steps:
+
+* Update the version in `CMakeLists.txt`,
+* Update the version in `vpckg.json`,
+* Update the version in 
+* Update the version in `Doxyfile`, and
+* Write an entry in `doc/changelog.md`.
+
+We use [SemVer] for versioning.
+Given a version number `MAJOR.MINOR.PATCH`, increment the:
+
+1) `MAJOR` version when you make incompatible API changes,
+2) `MINOR` version when you add functionality in a backward compatible manner, and
+3) `PATCH` version when you make backward compatible bug fixes
+
+Release candidates are suffixed with `-alpha.1`, `-alpha.2` *etc.*
+
+[SemVer]: https://semver.org/
+
+## Dependency Upgrades
+
+When you want to upgrade a dependency, make sure you update:
+
+* The version in `vcpkg.json`,
+* The required version in `find_package(...)` in `CMakeLists.txt`, and
+* The required version in `aas_core3-config.cmake`.

doc/main.md

@@ -14,7 +14,13 @@ For a detailed documentation of the API, see [API].
 
 For the background on some of the design decisions, see [Design Decisions].
 
+If you want to contribute, please see the [Contributing Guidelines].
+
+If you want to see how the SDK changed over time, see [Changelog].
+
 [the version 3.0 of the meta-model]: https://industrialdigitaltwin.org/content-hub/aasspecifications
 [Getting Started]: getting-started.md
 [API]: annotated.html
 [Design Decisions]: design-decisions.md
+[Contributing Guidelines]: contributing.md
+[Changelog]: changelog.md