Skip to content

Commit

Permalink
Merge pull request #332 from obophenotype/merge-docs
Browse files Browse the repository at this point in the history 
Update release workflow documents
  • Loading branch information
@rays22
rays22 authored May 13, 2024
2 parents 6ca0354 + e3355f9 commit 2d6894e
Show file tree
Hide file tree
Showing 2 changed files with 61 additions and 98 deletions.
82 changes: 1 addition & 81 deletions docs/oba-release-sop.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,84 +2,4 @@ Release Workflow for the Ontology of Biological Attributes (OBA)
================================================================


* Make sure you have the latest ODK installed by running docker:

```shell
docker pull obolibrary/odkfull
```

* Merge as many open PRs as possible.
* Start with a fresh copy of the `master` branch. For the next steps you can use [GitHub Desktop](https://desktop.github.com/) or the command line instructions below.

```shell
git pull
```

Create a new branch:

```shell
git checkout -b release-202X-XX-XX
```

In a terminal window, start the release pipeline:

```shell
sh run.sh make prepare_release_fast
```

NOTE: It is recommended that running the release pipeline is uncoupled from refreshing imports. However, inn case you need to refresh all the imports, you can achieve that by:

```shell
sh run.sh make prepare_release -B
```

- If everything went all right, you should see message similar to the one below in your terminal window:

> ...
> Release files are now in ../.. - now you should commit, push and make a release on your git hosting site such as GitHub or GitLab
> make[1]: Leaving directory '/work/src/ontology'
> Please remember to update your ODK image from time to time: https://oboacademy.github.io/obook/howto/odk-update/.

### Check and package the release artefacts for OBA

- You should also check in Protege if the new terms you just added look fine.
- Open in Protege some of the OBA release artefacts and check for any potential errors.
For example, check if there are any unsatisfiable classes in `oba.obo`.

- Create a pull request and get another pair of eyes to review it.
- Merge your `release-202X-XX-XX` branch into the master branch once approved by a reviewer and all the automatic quality control checks passed.

### Make a release and include all the release files (including oba-base.owl and oba.obo) as binary files

Use the [github web interface](https://docs.github.com/repositories/releasing-projects-on-github/managing-releases-in-a-repository?tool=webui) to create a new OBA release.

- There should be 15 recently modified files in the root directory of the local copy of the repo:
1. oba-base.json
2. oba-base.obo
3. oba-base.owl
4. oba-baseplus.json
5. oba-baseplus.obo
6. oba-baseplus.owl
7. oba-basic.json
8. oba-basic.obo
9. oba-basic.owl
10. oba-full.json
11. oba-full.obo
12. oba-full.owl
13. oba.json
14. oba.obo
15. oba.owl

- NOTE: GitHub imposes size constraints on repositories. The combined size of the OBA artefacts exceeds the GitHub imposed size limit. For this reason, some of the large release artefact files are not under GitHub version control. However, **all the 15 files need to be included in the public release as binary files**. For background information on release artefacts, see
- [OWL, OBO, JSON? Base, simple, full, basic? What should you use, and why?](https://oboacademy.github.io/obook/explanation/owl-format-variants/)
- [Release artefacts](https://oboacademy.github.io/obook/reference/release-artefacts/)

- Navigate to the ['Releases' page of OBA](https://github.com/obophenotype/bio-attribute-ontology/releases)
- Click `Draft a new release`.
Click `Chose a tag`, and create a new tag based on the date on which your ontologies were build. You can find this, for example, by looking into the oba.obo file and checking the `data-version:` property. The date needs to be prefixed with a `v`, so, for example `v2022-10-17`.
- For the title, you can use the date of the ontology build again, for example `2022-10-17 release`
- Drag and drop the files listed above or [manually select them in the binaries box.](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) using the github web user-interface.
- You can [automatically generate release notes.](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)
- Click `Publish release`. Done.

See the OBA-specific [ODK release workflow document.](odk-workflows/ReleaseWorkflow.md)
77 changes: 60 additions & 17 deletions docs/odk-workflows/ReleaseWorkflow.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,42 +12,85 @@ These steps are outlined in detail in the following.

Preparation:

1. Ensure that all your pull requests are merged into your main (master) branch
2. Make sure that all changes to master are committed to GitHub (`git status` should say that there are no modified files)
3. Locally make sure you have the latest changes from master (`git pull`)
4. Checkout a new branch (e.g. `git checkout -b release-2021-01-01`)
5. You may or may not want to refresh your imports as part of your release strategy (see [here](UpdateImports.md))
1. Ensure that all your pull requests are merged into your main (master) branch. Merge as many open PRs as possible.
2. Make sure that all changes to master are committed to GitHub (`git status` should say that there are no modified files).
3. Locally make sure you have the latest changes from master (`git pull`). You can also use [GitHub Desktop](https://desktop.github.com/) for interacting with the OBA repo.
4. Checkout a new branch (e.g. `git checkout -b release-202X-XX-XX`)
5. You may or may not want to refresh your imports as part of your release strategy (see [here](UpdateImports.md)).
6. Make sure you have the latest ODK installed by running `docker pull obolibrary/odkfull`
```shell
docker pull obolibrary/odkfull
```

To actually run the release, you:

1. Open a command line terminal window and navigate to the src/ontology directory (`cd oba/src/ontology`)
2. Run release pipeline:`sh run.sh make prepare_release -B`. Note that for some ontologies, this process can take up to 90 minutes - especially if there are large ontologies you depend on, like PRO or CHEBI.
3. If everything went well, you should see the following output on your machine: `Release files are now in ../.. - now you should commit, push and make a release on your git hosting site such as GitHub or GitLab`.

This will create all the specified release targets (OBO, OWL, JSON, and the variants, ont-full and ont-base) and copy them into your release directory (the top level of your repo).
1. Open a command line terminal window and navigate to the `src/ontology` directory (`cd bio-attribute-ontology/src/ontology`).
2. Start the release pipeline by issuing the command:
```shell
sh run.sh make prepare_release_fast
```
NOTE: It is recommended that you run the release pipeline uncoupled from refreshing imports. However, in case you do need to refresh all the imports at this time, you can achieve that by:
```shell
sh run.sh make prepare_release -B
```
3. If everything went well, you should see the following output on your machine:
```shell
...
Release files are now in ../.. - now you should commit, push and make a release on your git hosting site such as GitHub or GitLab
make[1]: Leaving directory '/work/src/ontology'
Please remember to update your ODK image from time to time: https://oboacademy.github.io/obook/howto/odk-update/.
```
This will create all the specified release targets (OBO, OWL, JSON, and the variants, ont-full and ont-base) and copy them into your release directory (the top level of your repo).

## Review the release

1. (Optional) Rough check. This step is frequently skipped, but for the more paranoid among us (like the author of this doc), this is a 3 minute additional effort for some peace of mind. Open the main release (oba.owl) in you favourite development environment (i.e. Protégé) and eyeball the hierarchy. We recommend two simple checks:
1. You should check in Protégé if there are any obvious errors in the ontology artefacts, for example, if there are unsatisfiable classes in `oba.owl` or `oba.obo. Two simple additional checks:
1. Does the very top level of the hierarchy look ok? This means that all new terms have been imported/updated correctly.
2. Does at least one change that you know should be in this release appear? For example, a new class. This means that the release was actually based on the recent edit file.
2. Commit your changes to the branch and make a pull request
2. Commit your changes to the branch and create a pull request and request another pair of eyes to review it.
3. In your GitHub pull request, review the following three files in detail (based on our experience):
1. `oba.obo` - this reflects a useful subset of the whole ontology (everything that can be covered by OBO format). OBO format has that speaking for it: it is very easy to review!
2. `oba-base.owl` - this reflects the asserted axioms in your ontology that you have actually edited.
3. Ideally also take a look at `oba-full.owl`, which may reveal interesting new inferences you did not know about. Note that the diff of this file is sometimes quite large.
4. Like with every pull request, we recommend to always employ a second set of eyes when reviewing a PR!
## Merge the main branch
Once your [CI checks](ContinuousIntegration.md) have passed, and your reviews are completed, you can now merge the branch into your main branch (don't forget to delete the branch afterwards - a big button will appear after the merge is finished).
Once your [CI checks](ContinuousIntegration.md) have passed, and your reviews are completed, you can now merge your `release-202X-XX-XX` branch into the main OBA branch (don't forget to delete the branch afterwards - a big button will appear after the merge is finished).
## Create a GitHub release
1. Go to your releases page on GitHub by navigating to your repository, and then clicking on releases (usually on the right, for example: https://github.com/obophenotype/bio-attribute-ontology/releases). Then click "Draft new release"
1. As the tag version you **need to choose the date on which your ontologies were build.** You can find this, for example, by looking at the `oba.obo` file and check the `data-version:` property. The date needs to be prefixed with a `v`, so, for example `v2020-02-06`.
1. You can write whatever you want in the release title, but we typically write the date again. The description underneath should contain a concise list of changes or term additions.
1. Click "Publish release". Done.
Use the [github web interface](https://docs.github.com/repositories/releasing-projects-on-github/managing-releases-in-a-repository?tool=webui) to create a new OBA release.
- There should be 15 recently modified files in the root directory of the local copy of the repo:
1. oba-base.json
2. oba-base.obo
3. oba-base.owl
4. oba-baseplus.json
5. oba-baseplus.obo
6. oba-baseplus.owl
7. oba-basic.json
8. oba-basic.obo
9. oba-basic.owl
10. oba-full.json
11. oba-full.obo
12. oba-full.owl
13. oba.json
14. oba.obo
15. oba.owl
- NOTE: GitHub imposes size constraints on repositories. The combined size of the OBA artefacts exceeds the GitHub imposed size limit. For this reason, some of the large release artefact files are not under GitHub version control. However, **all the 15 newly created ontology artefact files need to be included in the public release as binary files**. For background information on release artefacts, see
- [OWL, OBO, JSON? Base, simple, full, basic? What should you use, and why?](https://oboacademy.github.io/obook/explanation/owl-format-variants/)
- [Release artefacts](https://oboacademy.github.io/obook/reference/release-artefacts/)
1. Navigate to the ['Releases' page of OBA](https://github.com/obophenotype/bio-attribute-ontology/releases)
2. Click `Draft a new release`.
Click `Chose a tag`, and create a new tag based on the date on which your ontologies were build. You can find this, for example, by looking into the oba.obo file and checking the `data-version:` property. The date needs to be prefixed with a `v`, so, for example `v2022-10-17`.
3. For the title, you can use the date of the ontology build again, for example `2022-10-17 release`
4. Drag and drop the files listed above or [manually select them in the binaries box.](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) using the github web user-interface.
5. You can [automatically generate release notes.](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)
6. Click `Publish release`. Done.
* * * *
## Debugging typical ontology release problems
Expand Down

0 comments on commit 2d6894e

Please sign in to comment.