Workflows and procedures

Contents

• High level workflow
• Detailed procedures
  • Deploying the website
  • Starting new topics
  • Releasing new recommendations

High level workflow

[Edit this diagram here]

Our workflow will be to iterate through a list of areas in the JATS standard, the JATS documentation and the PubMed Central Tagging Guidelines where we can improve tagging standards and practice.

For each element, we will

• review existing practices,
• agree on best practice,
• issue draft recommendations,
• invite community feedback,
• issue formal recommendations, implement tools to help publishers identify whether their XML is compliant, and disseminate best practice tagging guidelines,
• publish reports on compliance - where it can be determined.

We are currently assembling our initial set of areas that we want to focus on, and we will publish those here.

Detailed procedures

Deploying the website

• You should be working in a matching branch for both website and validator. Note that everything in master is considered deployable; so, first test out your branch.

• From validator:

  • source bin/setenv.sh
  • source venv/bin/activate
  • bin/clean.sh
  • bin/setup.sh

• From website:

  • jekyll serve; this brings up a server on http://localhost:4000
  • Open up dev tools in your browser, and, for each page, make sure there are no 404s
  • Check the home page
  • Test the topics.html and jats-schemas.html pages
  • Test the validator

• Do a local, test deploy to ./_site:

  • ./deploy.sh --baseurl /path/to/jats4r/website/_site
  • Repeat the above tests using HTTP server of the static _site directory

• Create a test "package" and deploy it to jats4r.org/_test:

  • rm -rf _site
  • ./deploy.sh --baseurl /_test
  • rsync -e ssh --archive _site/ jats4r:/var/www/jats4r.org/_test
  • Test the site at http://jats4r.org/_test/

• Back up the existing site. From the jats4r machine:

  • cd /var/www
  • tar cvfz jats4r.org-YYYYMMDD.tgz jats4r.org

• Finally, deploy for real. Back on your local machine:

  • rm -rf _site
  • ./deploy.sh -- verify that this says "Deploying to ./_site; using BASEURL ''"
  • rsync -e ssh --archive _site/ jats4r:/var/www/jats4r.org
  • Test at http://jats4r.org

Starting new topics

For each new topic that the group decides to address (see the prioritization list):

• Define a "slug" for the topic. This is a simple hyphen-delimited, lowercase name; e.g. "math", "author-metadata'.
• Create a new Markdown file in the elements repository, using the slug name. E.g. "math.md".
• Create a new GitHub issues label for this topic.
• Create GitHub issues as needed, and invite participation

Releasing new recommendations

• Through GitHub issues and collaborative editing, get consensus on a set of topics/recommendations
• When there's a set of recommendations that are a candidate for release:
  • Decide on a new release number. E.g. "1.3".
  • Create branches of website and validator called "1.3-rc" (release candidate)
  • Copy the latest schema files into a new directory, schema/1.3, and commit them.
  • Make the changes to those, creating new .sch files for each new topic
  • Update update validator/schema/versions.yaml with the new version number.
  • Run bin/process_schematron.sh to produce the new version's XSLT
  • Migrate the draft recommendations into full-fledged github pages Markdown files.
  • Deploy a test version of the recommendations and validator to http://jats4r.org/test
  • Create a pull request, and invite votes. In the comments on the pull request, add a link to test site, where people can try things out.
  • Send an email to the mailing list, with a pointer to the pull request, and asking for up/down votes and discussion
  • When a quorum of votes has been gathered, merge the pull request
  • Tag all the relevant repositories with the version.