Skip to content

VSFS

Jump to bottom
Joe Wicentowski edited this page Sep 18, 2017 · 1 revision

VSFS

VSFS (Virtual Student Foreign Service) e-interns can participate remotely in HO initiatives through our GitHub repositories. While students could email their work to you, GitHub offers a sophisticated but easy-to-use version control system. In particular, GitHub works well with plain text file formats like XML files. All the student needs is an account on the service where the repository lives. Speak with Joe about your project to decide on the best approach.

Considerations

  1. Which repository will the student be contributing to? An existing repository or a new one? If an existing repository, the student should not commit directly to the master branch, but instead should work in a separate branch and submit work as a pull request.
  2. Should the work be done on GitHub or GitLab? Use the former for already public or public-bound work (most cases, preferred), or use the latter for work not intended for public dissemination (cumbersome, only if necessary).
  3. Do they need to be able to preview the data on a local instance of history.state.gov, or can they just edit the data in oXygen (or some other repository).

Add Student to VSFS Group

  1. Have student set up a GitHub account (and possibly also a GitLab account if determined above) and send you their username.
  2. Add the student to the HistoryAtState/VSFS group: https://github.com/orgs/HistoryAtState/teams/vsfs/members.
  3. Send the student the link to the next section, have them go through the setup steps.
  4. Send the student the link to the repository.

Student Setup

Welcome! GitHub is an easy-to-use version control system. These instructions will help get you set up.

  1. Create an account on the service you've been instructed to. Let your contact know your username.
  2. Download and install GitHub Desktop from https://desktop.github.com/ onto your computer.
  3. Open GitHub Desktop and log in.
  4. Open the link to the repository you've been instructed to. Click on the "Clone or download" button, and select "Open in Desktop." This will bring up the GitHub Desktop application and prompt you to choose a location to keep the repository files.
  5. Now you have a clone—a complete copy—of the repository on your computer. You can open the repository's files, work on them, and return to GitHub Desktop to send in your work when you're ready.

Committing your work

When you've finished work that you'd like to send in, open GitHub Desktop, and go to the "Uncommitted Changes" tab. This tab shows you all of the "changes" you've made: you'll have edited, added, deleted, and renamed files. Click on each filename in the list, and GitHub Desktop will show you what changed in each file: red represents the "old", green represents the "new." Selecting the checkbox next to a file means it will be included when you upload the file. Assuming you want to include all the files, select them all by clicking on the checkbox at the very top of the list (faster than selecting each checkbox!). Give the list a scan and confirmed the files are as you want them; you can still make changes to the files if you want.

Once you're ready to upload the files, here's what you'll do: Below the list of files is a pair of text boxes. Enter a brief summary of your changes in the first one, and use the second one if needed to add more notes. Then click on the "Commit to master" button beneath the text boxes. Then click on the "Sync" button in the top-right corner of the window. This will upload all of your changes to GitHub, and your "commit" will show up in the list of commits to the repository on GitHub's web page for the repository under "Commits."

From then on, you will do your work in the repository folder, and anytime you're done with your work for the day, "commit" your work and "sync" it to GitHub. Also, before you start your work for the day, hit "sync", and this will ensure you get any changes anyone else has made.

Clone this wiki locally