XDI Spec Drafting

Proposed Process for making changes

This process makes use of github, git, doc book, and Travis CI. Bill Barnhill will create more detailed examples with actual commands and will be setting up the process by creating org, repos, and Travis CI config.

  1. Edit the spec document you want to change, in the 'src' your local git repo for a particular document, cloned from a repo under https://github.com/organizations/OASIS-XDI-Technical-Committee

  2. Commit your changes with a commit message describing the changes
  3. When done making changes, push to remote repo on github
  4. This will automatically trigger building of the specs via post-commit tie-in to Travis CI, or if necessary to a separate build server, first by transforming them via XSL to XSL-FO, then to PDF. The resulting documents will be posted to the OASIS TC documents directory. Note that as part of this process the changes made in the git repo will be reflected back into the official OASIS Subversion repo, which will be the 'canonical' version control -- but if you commit to the subversion repo version of the specs your changes will be overwritten by this process.

Full process

  1. Get git
  2. Get a Github account
  3. Let me know your github account, so I add you to the TC organization as a collaborator
  4. Decide which doc to work on
  5. Clone the repo for that doc
  6. Set up that repo to use post-commit hook (I'll document this process once it's complete)
  7. Do your work as above in process for making changes
  8. Issue a pull request
  9. Participate in the discussion by tc members, using the GitHub pull request discussion mechanisms, until decision is made to merge in pull request by the TC (pretty much a default 'yes let's merge in, thank you for contributing' in most cases I suspect

  10. Bill will merge in the changes (and will set up at least one alternate to prevent a single point of failure).

Note: Bill will work out how to make sure docs are built with post-commit when an author pushes to your forked repo, but only synced with OASIS subversion when a push occurs on the master repo.

XdiSpecDrafting (last edited 2012-07-31 03:54:10 by drummond-xns)