Workflow for working on the spec

This is a collection of tips from David and Deyan on using git from the command line and working with the spec.

Git workflow

You can either clone the repo with the command line:

git clone git@github.com:w3c/mathml.git

or fork the repo:

• In the upper right hand corner of https://github.com/w3c/mathml, there is a fork command. This creates your private copy of the repo which you would then clone. The advantage of a fork is that you can share your changes with others so they can see them before pushing them back to the repo.

Workflow using a clone of w3c/mathml

When you start to work on something, then you need to work on a branch so that people can compare what you have done to the original (which is main):

Before you start work on something, it is best to do the following:

git pull --rebase

This will get you in sync with the upstream version and minimizes conflicts down the line.

You can then start your branch

git checkout -b myname/my-branch

It is not essential to prefix the branch name with myname/ (the GitHub Interface givs no significance to the /) but internally git does store branch data in subdirectories, and some git tools do allow you to browse the available branches using this structure)

It is even more useful to rebase immediately before you push your changes back to github - which ensures the smallest necessary difference will show in the Pull Request interface.

git pull
git rebase main

You may need to resolve conflicts during the rebase, if so do so in your text editor, then, git add the files and then

git rebase --continue

When you are ready to push your changes to gihub (which you can do any time, you do not need to wait until you have a final pull request ready)

git push --set-upstream origin myname/my-branch

(After the first push a simple git push will be enough, as git will store the tracking branch at github)

Try to avoid git merge unless absolutely necessary.

Git will prompt you wih a URL to gnerate a pull requst, but in general you can go to

https://github.com/w3c/mathml/pull/new/myname%2Fmy-branch

and fill in the details of the request.

Workflow using a Fork of w3c/mathml

After forking, you probably should link your copy to the original ("upstream"):

git remote add upstream https://github.com/w3c/mathml

When you start to work on something, then you need to work on a branch so that people can compare what you have done to the original (which is main):

You can either use the existing main branch, or generate a new branch as described above for a clone. If so you may want to use the pages tab in the settings menu of your fork to set GitHub Pages to use your branch as the source for GihUb Pages.

git checkout -b my-branch-with-changes

Before you start work on something, it is best to do the following:

git fetch upstream --all
git rebase upstream/main

This will get you in sync with the upstream version and minimizes conflicts down the line. It is even more useful to do this rebase immediately before you push your changes back to github - which ensures the smallest necessary difference will show in the Pull Request interface.

You may need to resolve conflicts during the rebase, if so do so in your text editor, then, git add the files and then

git rebase --continue
git push origin my-branch-with-changes

Try to avoid git merge unless absolutely necessary.

Working and viewing the spec locally

The MathML 4 draft is marked up using respec markup, so the sources are "almost HTML" (also as a convenience the sources are also well formed XML, although respec does not require that) The respec JavaScript processes the "live" sources giving the HTML rendering as seen at github pages. To find out what is available, see the respec manual.

While editing it helps to have a local webserver. On windows you can use the built-in IIS server (which may be enabled from the start menu) and in general apache or any other server may be used. If you have python a simple webserver is available. From the mathml directory, run

python -m http.server 8080

Then view the draft at http://localhost:8080/index.html in your browser.

If you want to use IIS and it isn't already installed/running:

1. Open your control panel, click on "Programs" (might be "Programs and Features" and then under "Programs and Features", click on "Turn Windows Features on and off"
2. In the new dialog, find "Internet Information Services" and click on it to enable it. Click "Ok" and wait while it is installed.
3. Type IIS in your command bar and click on Internet Information Services
4. In the app, click on "Directory Browsing" then "Advanced Settings" on the right.
5. Change Physical Path in the resulting dialog. Probably %SystemDrive% is good, but you can make it the location of your MathML repo to save typing
6. Open a webrowser to localhost/... where ... is the path relative to the value you just set to index.html in your repo.

Because there is MathML in the draft, using Firefox or turning on Chrome/Edge's MathML rendering is advised. To turn on rendering:

• in Chrome: chrome://flags/#enable-experimental-web-platform-features
• in Edge: edge://flags/#enable-experimental-web-platform-features

Click on the button to enable the features.

Working on the MathML notes

Working on the notes is similar to the above. The repository is at https://github.com/w3c/mathml-docs and the notes in particular are found in there at (surprise) notes-on-mathml.

Currently, working on the notes is very informal and PRs are not necessary.

The notes are in markdown and allow TeX for math.