Git Guidelines

These guidelines are suggested for use with this repository.

Definitions

Main Repository (on GitHub)

The main repository is located on GitHub at https://github.com/w-a-r-m-inventory-system/Food-Pantry-Inventory. This repository is the ultimate target of all changes. Currently it is managed by Shelby Elzinger.

Public Repository (on GitHub)

This is your public repository. It is also located on GitHub at an address something like https://github.com/userid/Food-Pantry-Inventory where userid is your GitHub user Id.

This repository is where you will push all your changes before submitting a pull request for them to be applied to the main repository.

Personal Repository (on your computer)

This repository is located on your local hard drive somewhere. It is characterized by having a “.git” directory under the top directory. That top directory will be the “project” directory for your copy of the WARM inventory system. Typically it will be the project directory for PyCharm.

Your personal repository will be linked to both the main repository and your public repository. Your personal repository will be the place you will create and test all changes before pushing them on.

Setting Up Your Working Environment

Setting Up Your Public Repository

  1. If you have not already done so, go to GitHub.com and create a user Id for your self.

  2. Login to GitHub with your user Id and credentials.

  3. Go to https://github.com/w-a-r-m-inventory-system/Food-Pantry-Inventory.

  4. Click on the box that says “Fork” in the upper right corner of the web page.

    1. This will create your public repository under your own area on GitHub.

  5. If this didn’t switch you back to your area of GitHub, click on the icon in the far upper right of the public repository web page to show a dropdown of choices about your area of GitHub. Click on the “Your repositories” choice.

  6. If not there already, click on your public repository labeled “Food-Pantry-Inventory”.

  7. Click on the green “Clone or download” button.

  8. Click on the little clipboard icon to the right of the URL that begins “https://github.com/…”.

    1. This will copy the full URL to your clipboard.

  9. Save this URL somewhere. You will need it to create your personal repository below.

  10. If you wish, you can go back to https://github.com/w-a-r-m-inventory-system/Food-Pantry-Inventory and click on the box that says “Watch”. This will notify you of changes made by other folks to the main repository.

Setting Up the PyCharm IDE

Our group has decided to all use PyCharm as our IDE for this project. Either the Community Edition (which is free) or the Professional Edition is fine. After installing PyCharm, configure it as follows to provide support for this project.

  1. Add these plugins:

    1. .ignore

    2. autodoc

    3. Markdown Navigator

    4. Codeglance (optional)

    5. PlantUML Integration (optional)

    6. String Manipulation (optional)

    7. Database Navigator (Optional)

Setting Up Your Personal Repository

  1. Verify that you have the URL saved in step 9 above.

  2. Start PyCharm. (If you have other projects open, please close them for the moment.)

  3. Choose “Checkout from Verson Control” from the right side of the dialog presentd by PyCharm.

  4. Paste the URL saved about into the URL box provided.

  5. Click on the “Test” button to verify that you have the correct URL to access your public repository on GitHub.

  6. Modify the value in the “Directory” box as needed and append “/Food-Pantry-Inventory” to it.

  7. Click on the “Clone” button to create your personal repository.

  8. Use PyCharm to establish a virtual environment for your personal repository.

    1. Click on Preferences (Settings) -> Project: Food-Pantry-Inventory -> Project Interpreter.

    2. It shows that this project is currently using the system Python install. We need to create a separate “virtual” environment to hold the libraries needed for this project and to protect the system Python from being “polluted” with these libraries.

    3. Click on the gear icon in the upper right corner.

    4. Click on Add in the dropdown.

    5. Verify that “Virtual Environmemt” is highlighted on the far left of the dialog the comes up, and that the “New Environment” radio button has been selected.

    6. Choose Python 3.7 as the base interpreter. (If 3.7 is not available, use 3.6 instead.)

    7. Click on OK, then OK again.

  9. Add these libraries/packages to the virtual environment.

    1. Sphinx - used for documentation

    2. sphinxcontrib-plantuml - used by Sphinx to include UML diagrams (created by PlantUML) in the Sphinx-generated documentation.

    3. Pytest - used for testing - expecially TDD

    4. PyYAML - used for managing configuration files

    5. Django - used for web part of project

  10. From the command line (either an external command prompt or using “Terminal” within PyCharm enter the following:

    git remote -v

  11. Verify that there are two lines for “origin”, that both point to your public repository, and that the first line has “(fetch)” while the second has “(push)” at the end.

  12. Enter the following commands to allow git to pull changes from the main repository.

    git remote add original https://github.com/w-a-r-m-inventory-system/Food-Pantry-Inventory.git
git remote -v

  13. Now you should see four lines. The first two are the same as before. The third and fourth lines should begin with “original” and the URL should be for the main repository.

    1. The label “original” is arbitrary. The following sections that discuss git and GitHub operations assume that “original” has been set this way.

  14. Install graphviz from https://graphviz.org/. This is needed for PlantUML.

Other PyCharm Settings

There are lots of other PyCharm settings that we have not specified. You are free to set this however you wish. There may be some settings that will be effectively overridden or ignored due to our adhering to PEP 8 or using a preformatting program such as black.

Git and GitHub Operations For Our Project

Make Local Changes

  1. Verify or set PyCharm to the master branch (should be in the very bottom right corner).

  2. Create a new branch with a name you substitute for <newbranchname> below (can be done manually in bottom right corner or in the terminal).

    git branch <newbranchname>

  3. Make the new branch active for changes.

    git checkout <newbranchname>

  4. Make whatever changes you wish to make.

  5. If you haven’t added new files to your personal repository any other way, add each file by highlighting it and using the menu VCS -> Git -> Add.

  6. Commit the changes to the git branch by clicking on the project folder (Food-Pantry-Inventory) and using the menu VCS -> Git -> Commit Directory… to bring up the commit dialog.

  7. Add a commit mesage.

    1. The first line should be a summary of the change and be less than 72 characters long.

    2. The second line should be blank.

    3. The third and subsequent lines should describe the details of what changed, e.g. files added, changed, or deleted and why.

    4. Change other areas of the commit dialog as needed.

    5. Click on the “Commit” button.

  8. Repeat as often as needed until your change is ready to be submitted to the main repository.

  9. Change back to the master branch with PyCharm or by typing in the terminal command area:

    git checkout master

  10. Merge the new branch into the master branch by typing:

    git merge <newbranchname>

  11. Now that the branch has been merged back into the master, the branch name can be discarded by typing:

    git branch -d <newbranchname>

Pushing Changes To Your Public Repository On GitHub

  1. Make changes as noted above. Be sure that you have merged your changes back into the master branch.

  2. If you have not already done so, switch back to the master branch.

  3. Enter the following command in the terminal command area:

    git push

    1. This applies the change to your public repository so others can see those changes.

  4. Verify that your public repository on GitHub has been updated by checking the web page for your repository. It should now say that your repository is now one (or more) commits ahead of the main branch.

Creating A Pull Request To The Main Repository

  1. After making a change (or a set of changes), committing them to the master branch and pushing the changes to your public repository, verify that all files and changes to files are reflected in your public repository.

  2. Log in to GitHub and go to your public repository.

  3. Click on the “New Pull Request” button.

  4. GitHub verifies that the changes can be applied to the main repository.

    1. GitHub checks for conflicts, a common ancestor starting point, etc.

  5. If GitHub allows the pull request to procede, a green “Create pull request” button will be available on the web page.

  6. Fill in a meaningful title and comments about why this pull request should be incorporated into the main repository, what issue(s) it resolves, etc.

    1. Markdown can be used in your comments. To see what GitHub allows for markdown see https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet.

  7. Click on the green “Create pull request” button.

  8. Send an email to Shelby that you have submitted a pull request.

Update Your Public Repository To Match The Main Repository (both On GitHub)

  1. Verify that your public repository says that it is one (or more) commits behind the main repository.

  2. Commit any changes you have outstanding to your current (non-master) branch.

  3. Switch to the master branch.

  4. Issue the following from the Terminal window or do the equvalent from PyCharm.

    git pull original master

git push

    1. The first command identifies the changes between the main repository and your personal master branch. It then automatically commits those changes to your personal repository.

    2. The second command pushs those same changes up to your public repository.

Here is a graphical representation of this process showing the steps involved.

@startuml (View Public Repository) as (vpr) User -> (Start) (Start) --> (vpr) note right of (vpr) Notice that your public repository is now one or more commits behind the main repository. end note (Prepare Local Repository) as (lr1) (vpr) --> (lr1) note right of (lr1) Switch back to master branch if not on master already. end note (git pull original master) as (lr2) (lr1) --> (lr2) note right of (lr2) This "**pulls**" the changes from the main repository and applies them to the local repository. If changes are from someone else, a commit message will be required. end note (git push) as (lr3) (lr2) --> (lr3) note right of (lr3) This "**pushes**" the changes up to your public repository that were just committed to your local repository. end note (lr3) --> (Done) @enduml

Updating From the Main Repository (Use Case)

Here is another graphical representation of this process showing the flow of information for each step.

@startuml maintainer -> main: Pull request accepted and applied main -> public: Now public repository is one or more commits behind main -> local: Change also puts local behind public <- user: User notices that their public repository is behind user -> local: git pull original master local <- main: Git pulls changes from main and applies changes to local local <- user: git push public <- local: git applies changes to public repository @enduml

Updating From the Main Repository (Sequence Diagram)