Workflow

Section A.2 Workflow

Here we outline the steps you need to take to contribute content to our shared textbook. The following is subject to change as we discover better ways to do things.

🔗

Broadly, there are three steps to contribute content.

Claim an issue on GitHub. This will avoid you competing against others to contribute first (and avoid conflicts in the files). Then pull the most recent version of the book from GitHub to work from, and create a branch to work on.
Add content locally (on your own machine) on your branch. When you are happy with your work (which you should compile with PreTeXt), you will commit the work to that branch.
Submit your work: first push your branch to GitHub. Then create a pull request so someone else can evaluate your work and add it to the official (master) branch.

🔗

The bolded terms above are all technical git/GitHub vocabulary. If you are not familiar with these, you should find a tutorial on git and GitHub to give you some background. It's not strictly necessary, but might make it easier to conceptualize the procedures outlined below.

🔗

One more note: there are multiple ways to do everything described here. For example, you might find it easier to use VS Code's interface instead of the web interface for GitHub. You might prefer to use the command line instead of VS Code's interface for git commands.

🔗

In the video below, I walk through an example of the workflow.

🔗

Subsection A.2.1 Claiming an Issue

🔗

Every time we decide as a class that something should be added to the book, one of use will “make an issue” on GitHub. This is done on the issues tab on the GitHub page for our project. Issues can be tagged and assigned to individuals or you can assign yourself.

🔗

As a rule for this course, you should not work on any part of the document that is unrelated to an issue to which you have been assigned (or to which you have assigned yourself). Collaboration is fine, but then everyone working on that issue should be assigned to it, and all those working on the issue should communicate amongst themselves (using the comments that are part of the issue) to decide on who does what.

🔗

Once you have claimed an issue, but before you can start working on it, you need make sure you have the most recent version of the project. In VS Code, open the workspace for the book. In the lower-left corner of the window you will see some “source control” info. Make sure it says “master” (you want to be on the correct branch). Now you are going to pull the most recent changes from the remote repository. You can do this using VS Code: go to the “source control” tab. The three dots at the top (views and more options) includes a menu for pull, push. You want to pull. (You can also, in a terminal, type git pull.)

🔗

Now create a new branch for the new work you will do. This can be done in the same menu (under Branch). Name the branch something descriptive, e.g., “add-thm-2-proof”. You should now see that as the branch name in the lower-left corner of the window.

🔗

Subsection A.2.2 Writing and Compiling

🔗

Now it's time to write. Add content, using proper PreTeXt markup. Using the pretext-tools extension should help a lot. Remember, everything needs to be inside some sorts of tags. Probably the most important thing to remember is to put each paragraph inside <p> tags. Using the extension, typing a “p” and hitting tab will start and end these for you and put your cursor in the right spot. Math goes inside <m> tags. Again, type “m” and hit tab.

🔗

To see your work, you will need to compile the document. Save the file you are working in (there is a setting in VS Code to autosave, which is useful). Assuming you have installed the PreTeXt command line interface (pip install pretextbook), you should be able to:

Open a terminal (in VS Code).
Type pretext build html, or pretext build html -d if you have added any tikz images that you want included.

🔗

To view the results, you can type pretext view and open a web browser to http://localhost:8000/. Rinse and repeat.

🔗

Once you are happy with what you have, you need to tell git this. You have made some changes, and now you need to commit them to (your local copy of) the repository. In the “source control” area of VS Code, click on the + next to the files listed under “changes”. This will stage them to be committed. Then you can enter a commit message that very briefly describes what changes are part of the commit. Finally, commit the staged files (the checkmark above the message).

🔗

To keep things clean, it would be helpful to put all the changes for a particular issue into one or two commits. The idea of a commit is that it is something that could be rolled back to an earlier state.

🔗

Subsection A.2.3 Submitting Your Work

🔗

Now you have some committed changes to one or more files in the local copy of the repository, on a branch. To submit this work, you need to publish the branch. You can do this using the source control 3-dot menu (Branch; Publish Branch).

🔗

If you make additional changes to the branch after publishing, then you can just push the branch (using the VS Code menu again).

🔗

Next, go to GitHub. You should see a pop-up message saying that you just pushed and would you like to create a pull request. Yes you would! Add a message describing what is included in the changes, and reference which issue the changes address (on GitHub, if you type #myissue, or similar, you will get an option of issues to choose from). Submit, and you are done.

🔗

Once I (or someone) approves your pull request (but not before), your changes will be merged into the master branch. At this point, you should do a pull on the master branch, and you can then safely delete your local copy of the other branch you made. Soon after, I will publish the changes on the course website so everyone can see them easily.