From b1f74b75548bc7ece82116bc450f448410b62b93 Mon Sep 17 00:00:00 2001 From: Brian Hoffman Date: Mon, 14 Mar 2022 13:36:10 -0400 Subject: [PATCH 1/2] update release doc to reflect simpler API document generation workflow --- development/release.md | 143 ++++++++++++++++------------------------- 1 file changed, 56 insertions(+), 87 deletions(-) diff --git a/development/release.md b/development/release.md index cb78ac10..c0d275fb 100644 --- a/development/release.md +++ b/development/release.md @@ -15,13 +15,44 @@ safest way of ensuring this is to clone the repo: git clone https://github.com/archivesspace/archivesspace.git ``` -This assumes you will be building a release from master. To build from a tag you - will need to additionally check out the tag, like this: +## Checkout the release branch -```shell -git checkout [tag-name] +If you are building a major or minor version (see [https://semver.org])(semver.org)), +start by creating a branch for the release and all future patch releases: + +``` shell +git checkout -b release-v1.0.x +git tag v1.0.0 +``` +If you are building a patch version, just check out the existing branch and see below: + +``` shell +git checkout release-v1.0.x ``` +Patch versions typically arise because a regression or critical bug has arisen since +the last major or minor release. If the "hotfix" has been merged to the release branch, +it will need to be cherry-picked back to the master branch. If it has been merged to the +master branch (more likely given current code review / QA workflow), it (they) will +need to be cherry-picked to the release branch. + +Consider the following scenario. The current production release is v1.0.0 and a critical +bug has been discovered. In the time since v1.0.0 was released, new features have been +added to the master branch, intended for release in v1.1.0: + +``` shell +git checkout master +git checkout -b oh-no-some-migration-corrupts-some-data +( fixes problem ) +git commit -m "fix bad migration and add a migration to repair corrupted data" +gh pr create --web +( PR is reviewed and approved on Github, QA'd, then merged to master) +git pull master +git checkout release-v1.0.x +git cherry-pick [SHA of hotfix commit] +git push origin release-v1.0.x +git tag v1.0.1 +``` ## Pre-Release Steps @@ -60,7 +91,7 @@ translations or multiple gem versions. This documentation is maintained on a separate [https://github.com/archivesspace/archivesspace/tree/gh-pages](gh-pages) branch in the ArchivesSpace repository, and consists of a -[Slate](https://github.com/tripit/slate) site (for REST API documentation), and +[Slate](https://github.com/archivesspace/slate) site (for REST API documentation), and the Ruby [YARD](http://yardoc.org/) documentation. Additional Technical Documentation (including this document) are maintained and served separately by the Technical Documentation sub-team at @@ -70,67 +101,40 @@ the Technical Documentation sub-team at 1. Check out a new branch from master ```shell - git checkout -b $version # $version = release tag to build (i.e. v2.8.0-RC1) - ``` + # if 1.0.0 has already been released: + git checkout release-v1.0.x -2. If you didn’t already bootstrap above, do so now - ```shell - build/run bootstrap + # if 1.0.0 has not yet been released: + git checkout -b release-v1.0.x ``` - -3. Run the documentation spec file to generate examples for the API docs + At this point you probably want to remove the gems in the `build` directory and + run bootstrap: ```shell - build/run backend:test -Dspec='documentation_spec.rb' + ./build/run bootstrap ``` - This runs through all the endpoints, generates factory bot fixture json, and spits it into a json file (endpoint_examples.json). - -4. Run the documentation Ant Task to generate the Yard documentation, create - the API.md index file, and rename the YARD index file. Optionally override - the version set in asconstants with an environment variable. +2. Run the doc:build task to generate Slate API and Yard documentation. (Note: the + API generation requires a DB connection with standard enumeration values.) ```shell - ARCHIVESSPACE_VERSION=X.Y.Z build/run doc:build + ARCHIVESSPACE_VERSION=X.Y.Z APPCONFIG_DB_URL=$APPCONFIG_DB_URL build/run doc:build ``` + This generates `docs/slate/source/index.html.md` (Slate source document) and `docs/doc/*` (Yard). -5. Build the Slate/API docs (using a standard Ruby) - *Note*: At present, middleman requires a bundler version < 2.0 so the docs have been updated to reflect this. - ```shell - cd docs/slate - gem install bundler --version '< 2.0' - bundle install --binstubs # if this fails, you may need to bundle update - ./bin/middleman build - ./bin/middleman server # optional if you want to have a look at the API docs only - rm -r ../api - mv build ../api - ``` -6. Preview the docs (optional) +3. (Optional) Run a docker container to preview API and Yard docs (you can do this as you develop as well). ```shell - cd .. # return to docs dir - ./bin/jekyll serve # to update bind-address add: -H 0.0.0.0 + docker-compose -f docker-compose-docs.yml up ``` + Visit `http://localhost:4568/api` to see the preview server render the api docs. + Visit `http://localhost:4568/doc` to see the preview server render the Yard docs. - - http://localhost:4000/archivesspace/api/ # api docs - - http://localhost:4000/archivesspace/doc/ # yard docs - -7. Commit the updates to git +4. Deploy the documentation. This will push `docs/slate/build` to [the gh-pages branch](https://github.com/archivesspace/archivesspace/tree/gh-pages). ```shell - cd ../ # go to top of the working tree - git add # all files related to the docs that just got created/updated (eg. docs/*, common/asconstants.rb, etc.) - #the following warning, if received, can be ignored: - #The following paths are ignored by one of your .gitignore files: - #docs/_site - #Use -f if you really want to add them. - git commit -m "Updating to vX.X.X" - ``` - -8. Push docs to the `gh-pages` branch (do not do this with release candidates) - ```shell - #SKIP THIS PUSH STEP FOR RELEASE CANDIDATES - git subtree push --prefix docs origin gh-pages - #or, if you get a FF error - git push origin `git subtree split --prefix docs master`:gh-pages --force + ./docs/slate/deploy.sh --push-only ``` + Published documents should appear a short while later at: + [http://archivesspace.github.io/archivesspace/api](http://archivesspace.github.io/archivesspace/api) + [http://archivesspace.github.io/archivesspace/doc](http://archivesspace.github.io/archivesspace/doc) ## Building a release @@ -143,43 +147,8 @@ the Technical Documentation sub-team at Replace X.X.X with the version number. This will build and package a release in a zip file. -2. Merge the updates back into master by creating and merging a PR. This - does not require a PR review (only in this case). - -3. Check out the master branch, pull, prune and tag it - ```shell - git checkout master - git pull --prune - git tag vX.X.X - git push --tags - ``` - -4. Delete the clone of ArchivesSpace used to build the release (though be sure - to retain the zip file you created above if you intend to continue to the - following section). This step is optional but recommended. - - ## Create the Release with Notes -### Review Milestone Assignments - -The release announcement needs to have all the tickets that make up the code -changes/contributions included in the release. These changes are identified by -the Github Milestone associated to each Pull Request. Therefore, you first -need to insure: - -1. That all PRs with the current milestone are closed. The following search on -GitHub's Pull Request page should return no results: -``` -is:open is:pr milestone:[current-milestone] -``` -2. That no recently merged Pull Requests were merged without having the current -milestone applied. The following search should only return old (before 11/2020) -or other "back of house" pull requests: -``` -is:pr no:milestone state:closed is:merged -``` - ### Build the release notes After reviewing the above, build the release notes: From 24759d01fce6134a4447e195047cfb6352c0e609 Mon Sep 17 00:00:00 2001 From: Brian Hoffman Date: Wed, 25 May 2022 16:50:13 -0400 Subject: [PATCH 2/2] update api and yard generation workflow --- development/release.md | 63 ++++++++++++++++++++++++------------------ 1 file changed, 36 insertions(+), 27 deletions(-) diff --git a/development/release.md b/development/release.md index c0d275fb..8836eef0 100644 --- a/development/release.md +++ b/development/release.md @@ -15,7 +15,7 @@ safest way of ensuring this is to clone the repo: git clone https://github.com/archivesspace/archivesspace.git ``` -## Checkout the release branch +## Checkout the release branch and create release tag If you are building a major or minor version (see [https://semver.org])(semver.org)), start by creating a branch for the release and all future patch releases: @@ -56,13 +56,6 @@ git tag v1.0.1 ## Pre-Release Steps -### Try to tie up any loose ends - -Before doing the release, it's a good idea to try and make sure nothing is left -hanging. Check JIRA for any tickets with the status of “Pull Request Submitted” -or “Rejected” and confirm there are no open Pull Requests in Github with the -current milestone. - ### Run the ArchivesSpace rake tasks to check for issues Before proceeding further, it’s a good idea to check that there aren’t missing @@ -97,45 +90,61 @@ Documentation (including this document) are maintained and served separately by the Technical Documentation sub-team at [https://github.com/archivesspace/tech-docs](https://github.com/archivesspace/tech-docs). -**Note** that these steps assume you're using a standard Ruby, not jRuby. +### Build the API docs -1. Check out a new branch from master +1. API documentation depends on the [archivesspace/slate](https://github.com/archivesspace/slate) submodule + and on Docker. Slate cannot run on JRuby. ```shell - # if 1.0.0 has already been released: - git checkout release-v1.0.x + git submodule init + ``` - # if 1.0.0 has not yet been released: - git checkout -b release-v1.0.x +2. Run the `doc:api` task to generate Slate API and Yard documentation. (Note: the + API generation requires a DB connection with standard enumeration values.) + ```shell + ARCHIVESSPACE_VERSION=X.Y.Z APPCONFIG_DB_URL=$APPCONFIG_DB_URL build/run doc:api ``` - At this point you probably want to remove the gems in the `build` directory and - run bootstrap: + This generates `docs/slate/source/index.html.md` (Slate source document). + +3. (Optional) Run a docker container to preview API docs. ```shell - ./build/run bootstrap + docker-compose -f docker-compose-docs.yml up ``` + Visit `http://localhost:4568` to preview the api docs. -2. Run the doc:build task to generate Slate API and Yard documentation. (Note: the - API generation requires a DB connection with standard enumeration values.) +4. Build the static api files. The api markdown document should already be in `docs/slate/source` (step 2 above). + The api markdown will be rendered to html and moved to `docs/build/api`. ```shell - ARCHIVESSPACE_VERSION=X.Y.Z APPCONFIG_DB_URL=$APPCONFIG_DB_URL build/run doc:build + docker run --rm --name slate -v $(pwd)/docs/build/api:/srv/slate/build -v $(pwd)/docs/slate/source:/srv/slate/source slatedocs/slate build ``` - This generates `docs/slate/source/index.html.md` (Slate source document) and `docs/doc/*` (Yard). +### Build the YARD docs -3. (Optional) Run a docker container to preview API and Yard docs (you can do this as you develop as well). +1. Build the YARD docs in the `docs/build/doc` directory: ```shell - docker-compose -f docker-compose-docs.yml up + ./build/run doc:yardoc ``` - Visit `http://localhost:4568/api` to see the preview server render the api docs. - Visit `http://localhost:4568/doc` to see the preview server render the Yard docs. -4. Deploy the documentation. This will push `docs/slate/build` to [the gh-pages branch](https://github.com/archivesspace/archivesspace/tree/gh-pages). +### Commit built docs and push to Github pages + +1. Double check that you are on a release branch (we don't need this stuff in master) and + commit the newly built documentation: ```shell - ./docs/slate/deploy.sh --push-only + git add docs/build + git commit -m "release-vx.y.z api and yard documentation" + ``` + + Use `git subtree` to push the documentation to the `gh-pages` branch: + ```shell + git subtree push --prefix docs/build origin gh-pages ``` Published documents should appear a short while later at: [http://archivesspace.github.io/archivesspace/api](http://archivesspace.github.io/archivesspace/api) [http://archivesspace.github.io/archivesspace/doc](http://archivesspace.github.io/archivesspace/doc) + Note: if the push command fails you may need to delete `gh-pages` in the remote repo: + ```shell + git push origin :gh-pages + ``` ## Building a release