Submit a correction using GitHub pull requests - PerseusDL/canonical-greekLit GitHub Wiki

Making minor corrections to existing works.
Note, significant changes to an edition may call for a change to the file name. Please ask if you are unsure if you should be creating a new edition.

Concise Version

  1. For many texts, it is now possible to perform forking, branching, and pull requests via the GitHub web interface.
  2. For example, if you want to make minor edits, just browse to the text in question and look for the Edit pen icon. It will be just above the text window on the right side after Raw - Blame - History buttons and before the Trash can. When you click on the Edit pen icon, you may see a message that reads:

    You’re editing a file in a project you don’t have write access to. We’ve created a fork of this project for you to commit your proposed changes to. Submitting a change to this file will write it to a new branch in your fork, so you can send a pull request.

  3. After making the appropriate edits, add a message and description at the bottom of the page, near the Propose File Change dialog. In the first box, it is helpful to include the file name and a brief description such as:
    (tlg0012.tlg001.perseus-grc2.xml) missing line numbers
    In the second box, you may add more information such as:
    Line numbers 5.156 and 7.234 were added
  4. Following the proposed changes, you will be taken to a Comparing changes window that permits you to see the file before and after your edits. If the edits read as you like, you may proceed to Open a Pull Request.
  5. We will review and comment on your Pull Request as soon as possible. Thanks for submitting it!

Long version

  1. Search open issues for your work. There may be work in progress related to your correction.
  2. If an existing issue has not been found, create an issue in the repo using a descriptive name:
    (file name) description
    e.g.
    (tlg0012.tlg001.perseus-grc2.xml) missing line numbers
  3. Clone the repo and pull from Master.
  4. Create a branch from Master.
    e.g. tlg0012.tlg001 or tlg0012.tlg001_edits
  5. Make local corrections to the file on this new branch.
    Note for step 6: Not all users will have check in permissions. If you do not have check in permissions, simply skip to step 7.
  6. When checking in your edits, include the branch name and number of the issue created in step 1.
    e.g. (tlg0012.tlg001) added missing line number 3.21 #425
  7. View Hook tests for your check ins to confirm that all tests are passing.
    a. Go to repo page https://github.com/PerseusDL/canonical-greekLit
    b. Click on "coverage" at bottom of the page to go here http://ci.perseids.org/repo/PerseusDL/canonical-greekLit
    c. Look for your build and click on the Build number. This will take you to a Travis CI page with further Hook testing information.
    d. Look for your file name in the logs and see if it is passing.
  8. Create a Pull Request for your issue when are you done with your edits and all tests are passing.
    This can be done via the GitHub GUI, command line, or other software. In most cases, the repo home page will show you the most recent changes to your branches (Your recently pushed branches.) and have a Compare and Pull Request option at the top of the page that will open this option for you.
  9. On the Pull Request page, in the body of the Pull Request message say you are fixing the issue you created:
    (tlg0012.tlg001) missing line numbers
    fix #425
    This will enable the issue to be easily closed when the Pull Request is complete.
  10. Assign someone to review your Pull Request whenever possible.
    The reviewer may add comments and suggestions for making additional changes.
  11. Once the Pull Request is accepted, pull from Master. You may delete your branch. Your issue should now be closed.