|
1 | 1 | # Contributing |
2 | 2 |
|
3 | | -When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other |
4 | | -method with the owners of this repository before making a change. |
| 3 | +Before contributing to this repository, please discuss the intended change with the repository owners. |
| 4 | +This can be done via [issues], [discussions], email, or any other available method. |
5 | 5 |
|
6 | 6 | Please note we have a code of conduct, please follow it in all your interactions with the project. |
7 | 7 |
|
8 | | -## Pull Request Process |
9 | | - |
10 | | -1. Ensure any unnecessary install or build dependencies and other files are removed before the end of the layer when |
11 | | - doing a build. |
12 | | -2. Explain the changes and update the README.md file and other documentation if necessary. |
13 | | -3. Be ready to communicate about the Pull Request and make changes if required by reviewers. |
14 | | -4. The Pull Request may be merged once it passes the review and automatic checks. |
15 | | - |
16 | | -## Gitflow Workflow |
17 | | - |
18 | | -We use the standard [Gitflow Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow): |
19 | | - |
20 | | -* __master__ branch is used only for releases (and eventually hotfixes), this branch is also protected on GitHub (pull |
21 | | - requests with review and all checks must pass) |
22 | | -* __develop__ branch is used for development and as a base for following development branches of features, support |
23 | | - stuff, and as a base for releases |
24 | | -* __feature/*__ (base develop, rebase-merged back to develop when done) |
25 | | -* __chore/*__ (like the feature but semantically different, not the feature but some chore, e.g., cleanup or update of |
26 | | - Dockerfile) |
27 | | -* __fix/*__ (like the feature but semantically different, not something new but fix of a non-critical bug) |
28 | | -* __release/*__ (base develop, merged to master and develop when ready for release+tag) |
29 | | -* __hotfix/*__ (base master, merged to master and develop) |
30 | | - |
31 | | -Please note, that for tasks from [our Jira](https://dtl-fair.atlassian.net/projects/FDP/issues), we use such |
32 | | -as `[FDP-XX]` identifying the project and task number. |
33 | | - |
34 | | -## Release Management |
35 | | - |
36 | | -For the release management we use (aside from |
37 | | -the [Gitflow Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)): |
38 | | - |
39 | | -* [Semantic versioning](https://semver.org) |
40 | | -* Release Candidates - X.Y.Z-rc.N should be created if don’t expect any problems (in that case use alpha or beta), and |
41 | | - make a walkthrough to verify its functionality according to the manuals finally - it also verifies that the |
42 | | - documentation is up to date with the new version. |
43 | | -* [CHANGELOG.md](https://keepachangelog.com/en/1.0.0/ ) |
44 | | -* GitHub releases and tags - make the release using GitHub (or hub extension), CI will automatically upload ZIP and TGZ |
45 | | - distribution files there - better verify. |
46 | | -* Docker Hub image - in case of release, Docker image with the same tag will be created automatically. |
47 | | -* The matching version of [FDP](https://github.com/FAIRDataTeam/FAIRDataPoint) |
48 | | - , [FDP-Client](https://github.com/FAIRDataTeam/FAIRDataPoint-client), |
49 | | - and [OpenRefine extension](https://github.com/FAIRDataTeam/OpenRefine-metadata-extension) must be always compatible. |
50 | | - |
51 | | -Also, never forget to update the |
52 | | -joint [FAIR Data Point documentation](https://github.com/FAIRDataTeam/FAIRDataPoint-Docs)! |
| 8 | +>[!IMPORTANT] |
| 9 | +>Code generated using any form of AI, LLM, or similar tools, ***MUST*** be clearly labeled as such in the PR. |
| 10 | +
|
| 11 | +## Version control workflow |
| 12 | + |
| 13 | +Our version control workflow is pragmatic, aiming to minimize overhead for a small team. |
| 14 | +It resembles [github flow] with some aspects of [git flow] and [trunk-based development], but does not really fit well in any of those boxes. |
| 15 | + |
| 16 | +- We have a single `master` branch which is supposed to remain stable. |
| 17 | +- For every *significant* change, we create a new short-lived branch from `master`. |
| 18 | +- We immediately create a pull request (PR) for the new short-lived branch. |
| 19 | +- We push often, at least once a day. |
| 20 | + This allows us to keep track of work in progress and provide guidance before things get off track. |
| 21 | +- After merging back into `master`, the short-lived branch is deleted. |
| 22 | +- Rebasing and force pushing the *short-lived* branch is allowed only *if* the corresponding PR does not have any comments yet. |
| 23 | + This ensures the comments remain in context. |
| 24 | +- Releases are created directly from the `master` branch. |
| 25 | +- Only the latest major release is supported. |
| 26 | + |
| 27 | +Note that there is still a `develop` branch, but that is legacy. |
| 28 | + |
| 29 | +## Pull requests are used for significant changes |
| 30 | + |
| 31 | +All significant contributions should be added via [pull requests] (PRs). |
| 32 | +This allows us to discuss and review the changes, and document design choices. |
| 33 | +Very minor changes, like fixing a typo in the readme or a comment, can sometimes be pushed directly onto master. |
| 34 | + |
| 35 | +Pull request titles must be *concise* and *descriptive*. |
| 36 | +This enables auto-generation of meaningful change logs during the release process. |
| 37 | + |
| 38 | +## Pull requests must be focused |
| 39 | + |
| 40 | +Individual PRs *must* have a strong focus which is clear from the title. |
| 41 | +When writing the title, remember that it is the only thing users will see in the change log. |
| 42 | +PRs should also have a clear description and rationale, and should be linked to relevant issues, if any. |
| 43 | + |
| 44 | +If a PR gets very large, split it up into smaller PRs that can be reviewed separately. |
| 45 | + |
| 46 | +## Merge method is chosen depending on content |
| 47 | + |
| 48 | +Depending on the size and type of PR, different [merge methods] can be applied. |
| 49 | +We prefer a squash merge for small PRs, resulting in a single commit. |
| 50 | +However, in some cases, it may be useful to keep the individual commits from the PR. |
| 51 | +In that case we use a merge commit (as in `--no-ff`). |
| 52 | + |
| 53 | +## External dependencies are minimized |
| 54 | + |
| 55 | +To reduce the maintenance burden, we aim to minimize the number of external dependencies. |
| 56 | +If external dependencies cannot be avoided, we prefer well-supported projects with large numbers of contributors. |
| 57 | + |
| 58 | +## Semantic versioning applies to the API |
| 59 | + |
| 60 | +Release versions are based on [semantic versioning], i.e. `major.minor.patch`. |
| 61 | +However, the semantic versioning rules for `major` changes are only applied to changes in the HTTP API. |
| 62 | +For example, breaking changes in application *configuration* may occur in `minor` versions, as long as these changes are not reflected in the HTTP API. |
| 63 | + |
| 64 | +[discussions]: https://github.com/FAIRDataTeam/FAIRDataPoint/discussions |
| 65 | +[git flow]: https://nvie.com/posts/a-successful-git-branching-model/ |
| 66 | +[github flow]: https://githubflow.github.io/ |
| 67 | +[issues]: https://github.com/FAIRDataTeam/FAIRDataPoint/issues |
| 68 | +[merge methods]: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github |
| 69 | +[pull requests]: https://github.com/FAIRDataTeam/FAIRDataPoint-client-redux/pulls |
| 70 | +[releases]: https://github.com/FAIRDataTeam/FAIRDataPoint/releases |
| 71 | +[semantic versioning]: https://semver.org |
| 72 | +[trunk-based development]: https://trunkbaseddevelopment.com/ |
0 commit comments