forked from openml-labs/server-demo
-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add contributing guide, continue reorganisation
- Loading branch information
Showing
6 changed files
with
193 additions
and
78 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,97 @@ | ||
| # Contributing | ||
|
|
||
| You're looking to contribute to the AI-on-Demand metadata catalogue, that's great! | ||
| AI-on-Demand is an open project and we welcome contributions by all, no matter their experience or background. | ||
|
|
||
| ## Types of Contributions | ||
| There are many types of contributions to be made to the metadata catalogue, and this section | ||
| covers a non-exhaustive list. If you find something that's not outlined here, just reach out to us! | ||
|
|
||
| ### No Code | ||
| Good examples for contributions that do not require any coding include: | ||
|
|
||
| - Giving [our GitHub repository](https://github.com/aiondemand/AIOD-rest-api) a star ⭐️ | ||
| - [Helping people on the GitHub issue tracker](#helping-people-on-github) 🤝 | ||
| - [Reporting bugs](#reporting-bugs) 🐛 | ||
|
|
||
| ### Documentation | ||
| You can help improve our documentation by correcting mistakes, such as typos, adding clarifications, | ||
| or even adding new sections. For small changes, documentation can be edited directly on GitHub by | ||
| finding the related markdown file and clicking the pencil icon in the top-right corner (✐). | ||
|
|
||
| If you intend to make bigger changes, please first open a new issue the documents the suggested change. | ||
| That way, we can give you feedback before you write, and verify that it is actually a change we would be interested in adopting. | ||
| For big changes, we also recommend you to follow the instructions on ["Setting up a development environment"](#setting-up-a-development-environment) | ||
| so that you can render the changed documentation locally. | ||
|
|
||
| ### Code | ||
| For code changes, please first co-ordinate with the developers on what you will work on. | ||
| You can do this by either leaving a comment on an existing issue that you would like to help with, | ||
| or by opening a new issue proposing your change. By first communicating with the developers, they | ||
| can let you know ahead of time whether or not the change is wanted, make sure they have time to | ||
| support you, and provide any feedback. We really want to avoid a scenario where you may work hard on a contribution | ||
| only to find out that it is not in line with the vision of the project and thus will not be accepted. | ||
| When starting your first code contribution, visit the ["Setting up a development environment"](#setting-up-a-development-environment) | ||
| section for more information on how to get started. | ||
|
|
||
| ## Helping people on GitHub | ||
| Helping people on the [GitHub issue tracker](https://github.com/aiondemand/AIOD-rest-api/issues) just requires a GitHub account. | ||
| You can help by people by answering their questions, or weighing in on discussions. | ||
| Even if you do not have an answer, you can verify that you can reproduce the behavior they report or | ||
| ask clarifying questions to make their bug report better (see also ["Reporting Bugs"](#reporting-bugs)). | ||
| This helps the core contributors resolve the issue with more ease and is hugely appreciated. | ||
| As always, please be kind and patient with others. | ||
|
|
||
| ## Reporting Bugs | ||
| When you find a bug and want to report it, the first step is to check that it has not already been reported. | ||
| Use the search functionality of the GitHub issue tracker to find identical or related issues. | ||
| If your issue or bug has already been reported, please do not open a new issue. | ||
| Instead, either "upvote" the original report by leaving a 👍 reaction or, | ||
| if you have additional information which may be relevant to the discussion, leave a comment on that issue. | ||
|
|
||
| If your bug isn't reported yet, create a new issue. | ||
| Provide a clear explanation of the expected behavior and the observed behavior, and explain why you think this is a bug. | ||
| Add instructions on how to reproduce the expected behavior through a [Minimal Reproducible Example](https://stackoverflow.com/help/minimal-reproducible-example). | ||
| Without it, it may be very hard for contributors to solve the issue (or may not even understand it). | ||
|
|
||
| ## Setting up a development environment | ||
|
|
||
| ### Cloning | ||
| First, make sure you can get the local metadata catalogue up and running by following the ["Hosting" instructions](Hosting.md). | ||
| During the installation step, use `git` to clone the repository. | ||
| If you have write access to this repository, you can follow the instruction as-is. | ||
| If you do not have write access to this repository, you must [fork it](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo). | ||
| After forking the repository, your clone command will be (substituting `USERNAME` for your GitHub username): | ||
|
|
||
| ```commandline | ||
| git clone https://github.com/USERNAME/AIOD-rest-api.git | ||
| ``` | ||
|
|
||
| ### Installing Dependencies | ||
| Always make sure to install your dependencies in a local environment, for example with the built in `venv` module: | ||
|
|
||
| ```commandline | ||
| python -m pip venv venv | ||
| source venv/bin/activate | ||
| ``` | ||
|
|
||
| and then install the Python dependencies | ||
|
|
||
| ```commandline | ||
| python -m pip install -e ".[dev, docs]" | ||
| ``` | ||
|
|
||
| we install the optional `dev` (developer) and `docs` (documentation) dependencies so that we can | ||
| build documentation and run tests locally. | ||
|
|
||
| ### Configuration | ||
|
|
||
| It is also generally useful to set add an `override.env` file to the project's root directory with | ||
| the line `USE_LOCAL_DEV=true` added. This will allow utility scripts `./scripts/up.sh` and `./scripts/down.sh` | ||
| to start docker containers in a way that reflects local changes. | ||
|
|
||
| ## Making a Code Changes | ||
| See the ["Developer Documentation"](developer/index.md) for the technical documentation of this project. | ||
| More to be added. | ||
|
|
||
| [//]: # (## Setting up a pull request) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,63 @@ | ||
| # Releasing and Versioning | ||
|
|
||
| The project loosely uses [Semantic Versions](https://semver.org) where the patch/micro number matches the release date. | ||
|
|
||
| ## Breaking changes | ||
|
|
||
| !!! note "Work in Progress" | ||
|
|
||
| Guidelines in "Breaking Changes" are the desired workflow, but in practice we are not always following them | ||
| as 1) the metadata model wasn't yet matured and 2) the infrastructure for this needs to be | ||
| developed. For now, we make sure all URLs are at least under a version suffix, which makes | ||
| support in the future possible. | ||
|
|
||
| Breaking changes of a resource include deleting a field, changing the name of an existing field, | ||
| or changing the datatype of a field. Adding new fields is not a breaking change. | ||
|
|
||
| On a breaking change for a resource (e.g. for Dataset), a new router with a new version should | ||
| be created. The existing router should be deprecated, and rewritten so that it can handle the | ||
| new metadata of the database. This deprecation of a router will be visible in the Swagger | ||
| documentation. Calls to a deprecated router will still work, but a response header "Deprecated" | ||
| will be added with the deprecation date. The deprecated router will then be deleted on the next | ||
| release. | ||
|
|
||
| On non-breaking changes of a resource, a new version is not needed for the corresponding router. | ||
|
|
||
| Example: | ||
| - Start www.aiod.eu/api/datasets/v0 | ||
| - Release 1: www.aiod.eu/api/datasets/v0 (no breaking changes) | ||
| - Release 2: | ||
| - www.aiod.eu/api/datasets/v0 (deprecated) | ||
| - www.aiod.eu/api/datasets/v1 | ||
| - Release 3: www.aiod.eu/api/datasets/v1 | ||
|
|
||
| ## Changelog | ||
|
|
||
| As changelog we use the Github tags. For each release, a release branch should be created with a | ||
| bumped version in the pyproject.toml, and merged with the master. The tag should contain a | ||
| message detailing all the breaking and non-breaking changes. This message should adhere to the | ||
| guiding principles as described in https://keepachangelog.com/. | ||
|
|
||
| - Show all tags: https://github.com/aiondemand/AIOD-rest-api/tags | ||
| - Show a specific tag: https://github.com/aiondemand/AIOD-rest-api/releases/tag/0.3.20220501 | ||
|
|
||
| This information can also be extracted using the Github REST API. | ||
|
|
||
|
|
||
| ## Creating a release | ||
| To create a new release, | ||
| 1. Make sure all requested functionality is merged with the `develop` branch. | ||
| 2. From develop: `git checkout -b release/[VERSION]`. Example of version: `1.1.20231129` | ||
| 3. Update the version in `pyproject.toml`. | ||
| 4. Test all (most of) the functionality. Checkout the project in a new directory and remove all | ||
| your local images, and make sure it works out-of-the box. | ||
| 5. Go to https://github.com/aiondemand/AIOD-rest-api/releases and draft a new release from the | ||
| release branch. Look at all closed PRs and create a changelog | ||
| 6. Create a PR from release branch to master | ||
| 7. After that's merged, create a PR from master to develop | ||
| 8. Deploy on the server(s): | ||
| - Check which services currently work (before the update). It's a sanity check for if a service _doesn't_ work later. | ||
| - Update the code on the server by checking out the release | ||
| - Merge configurations as necessary | ||
| - Make sure the latest database migrations are applied: see ["Schema Migrations"](developer/migration.md#update-the-database) | ||
| 9. Notify everyone (e.g., in the API channel in Slack). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters