Lifecycle of a Doc Change in the IVOA repo

Overview

Working session to learn (following existing documentation, and updating where necessary) the lifecycle of making a change to the VOTable document, actually making the change in the repository. It seems important that we all know the recommended path through the tools and processes.

Notes

Number of attendees: 44

Where should documentation live??

Draft a pull request for the doc and store it where we decide

How should it be maintained?? - In github
Markus would like to have the baseline documentation in ivoatexDoc. That's where currently volute instructions are, and they probably ought to go anyway when we're retiring volute.
How much git crib should be in there is a different question. And having a one-page crib might be a good thing anway (though that could still live in the ivoatexdoc repo in whatever shape).

Process should be similar to that used by AstroPy/PyVO

Process was presented in Groningen - we will follow that thread

Test it out, get feedback, modify if needed - where are the pain points??

Working through the thread:

Hosted on https://github.com/ivoa-std - Repo is the main entry point
Master shows latest work on next version - publicly available
Pull request - asking maintainers to pull your change into the repo
IVOA is using the recommended GitHub flow

Exercise:

In VOTable repository
Add a new author to the document - Issues tab has exercise itemized
Fork the Repo - complete copy goes into your user space
- can be done once on your lifetime -or- reseeded many times **decsion on policy later*
- Click on Fork to get your copy - you get a complete copy of the votable repo in your space
- Then you can see in your own space - the repo (shows it's been forked from ivoa-std)
- Recommended that you DO NOT work on the master branch of your fork!!
- You can delete your master branch after your fork - on github (recommended)
  - Theory behind it; separates pull requests - want them separate
- Setting tab / then Braches / you can change what your default branch is, we'll name placeholder
  - placeholder/replace branch
- Now named placeholder
- Under Code there is a braches subtab - we see placeholder (our branch)
- Can keep Fork around for ever and skip the step next time
Next, Clone repo - bring down to your machine to do work
- Performed through Desktop (need to download it) - may been to move to Applicaiton dir if on Mac
  - shows if there have been changes; check in dir listed to see files on disk
- Can also clone thru command line - set of commands that Tom scripted (link provided in presentation)
  - Clone at your repo and make it VOTable; script ensures 'remote' name
  - icalling script -> voa_clone VOTable
  - -recurse submodule - it includes the building blocks of the IVOA (latex building blocks) automatically
Branch next ...
- Click on current branch and name new branch
- Now you have a choice - choose branch off of upstream/master, click
Make the change
- Repository menu (at top) - can show you where your repo is in the Finder; also with visual studio code which is in the menu
- Incidentally, if you're curious what you can make, ivoatexDoc is your friend: http://ivoa.net/documents/Notes/IVOATex/
- Output is a PDF - not in Github; gets built with makefile; can run make in VoTable directory (need java for VoTable) - Need to install Latex on your computer if missing; see VoTable.pdf if it was successful
  - ensures the thread before editing
  - Look at PDF
- To Add an author - edit VOTable.tex; find text / make change / save file
- Go back to make and remake the doc; see the author change if successful in the PDF
Go back to desktop and see everything that changed in the directory - most files you see were generated by the makefile/latex
- Don't want to check-in any artifacts from the make, back into github
- Only want to commit VOTbale.tex (not the other files)
- there is a template for svn:ignore in ivoatex at that point -- this should be ported to .gitignore
- Type a description in the window for the commit (add-fred branch)
- Commit the change - in local repo now
Next step to publish to github (to your personal repo)
- Under placeholder you see add_fred
- See VOTable.tex - check and see change
- Go to add-fred branch - initiate pull request
  - fill in title - 'add fred as author' and more in box lower provided; site issue you are fixing! Include # and it lists the issues and you can pick the right one.
  - Then click 'create pull request'
Next comes the review
- Can add comments to the change (finish your review) to complete
- Can add a suggestion with '+' and you can leave a suggestion; can give ok

Suggestions to fo further

Good set of notes in slides that everyone can try ... there is a desktop and command line approach - try both
Followup meeting to compelte thread

note https://github.com/github/hub if you want to do some github interactions from the commandline.

** Convention update

Add issue number to pull request!!!

Running Questions

LM Do you mean we should use GIT flow?
[JD] Most IVOA repositories are using GitHub flow - a simpler flow that uses wbranches and pull requests to build up just a master branch. See https://guides.github.com/introduction/flow/ 

PT:   i was always in hte habit of sticking to "origin" where I cloned from (my fork) and always call the original ivo in this case, the "upstream". I'll think about this flow.

args, i forgot the recursive trick. how to post fix this?
git submodule init
git submodule update
args, now i need javac on my spanking new ubuntu20:     many options.... I tried this:
    sudo apt install openjdk-14-jdk-headless
and victory!!!!   "make" produced th PDF.

Igor - why GitHub and not overleaf??

I would still suggest we have a HelloWorld type document, that allows more tinkering (issue 1 on VOTable).
This is also where the README.md file can explain the steps for commandline gurus.

I tried this process on VOEvent, and failed: - is this worthy an issue, or my bad?

$ make
rm -f ivoatexmeta.tex
touch ivoatexmeta.tex
echo '% GENERATED FILE -- edit this in the Makefile' >>ivoatexmeta.tex
/bin/echo '\newcommand{\ivoaDocversion}{2.0}' >>ivoatexmeta.tex
/bin/echo '\newcommand{\ivoaDocdate}{2011-07-11}' >>ivoatexmeta.tex
/bin/echo '\newcommand{\ivoaDocdatecode}{2011-07-11}' | sed -e 's/-//g' >>ivoatexmeta.tex
/bin/echo '\newcommand{\ivoaDoctype}{REC}' >>ivoatexmeta.tex
/bin/echo '\newcommand{\ivoaDocname}{VOEvent}' >>ivoatexmeta.tex
make: *** No rule to make target 'role_diagram.xml', needed by 'role_diagram.svg'. Stop.