הפרויקט השנתי בהנדסת תוכנה Git and GitHub Tom Palny, CS Department Software and Systems Development Laboratory The Technion Winter 2017

מה ההבדל ביניהם GIT: ניהול גרסאות קוד *לוקאלי* GITHUB: אחד מכמה שירותי ענן שמספק: שמירת גרסאות קוד כלים לניהול פרויקטים ומשימות לצוותים, סטטיסטיקות, issues, תיעוד חיצוני (wiki), שימוש בכלים אוטומטים לבדיקות איכות קוד כמו C.I., test coverage וכו.

Git & GitHub העבודה ב- Git וב- GitHub קיימת בשני מישורים ניהול קוד ניהול וחלוקת משימות Git Workflow

בקורס נתייחס לשלושה חלקים: Git & Github: Local code management, set up and usage, Synching the work with the cloud and how to avoid conflicts Teamwork: Issues management Documentation: Wiki & Readme

Git & Github Go to Github and create a new project in the organization TechnionYearlyProject You’ll see the following page:

Git & Github Open a terminal (cmd for windows or bash for linux) in your computer and navigate to a directory in which you want your project’s code to reside and type: git clone https://github.com/TechnionYearlyProject/YourNewlyCreatedProject.git Done. Memorize: 1. Commit 2. Pull 3. Push

Git & Github “git commit”: local to your computer. When you’re done working, and want to take a snapshot of the current code on your *local* machine. you’ll need to give it a commit message, which will be the commit title in github. “git pull”: BEFORE you put your code in the common repository on Github, you must update your local files, i.e. Pull from the cloud. Here you will find out if there are conflicts between your own code and the server code and get a chance to choose which is the one to keep. “git push”: after resolving conflicts (if any), this will then push your local code to the remote Github repository.

Commented out code - regulations   You are free to comment out code in your own local copy But, you never push code that is commented out. You know why you commented it out No one else does Commented out code tends to live longer than real code since no one really understands it Commented out code is a sign that you do not understand: this tutorial / team work / good use of Git

Do not push commented out code   What do I do when I see someone’s commented out code after “git pull”? You erase it immediately. Whomever pushed it will understand

Git & Github In each “commit message”, the title of the commit in Github, you must include the Issue# (more on this coming up next) that the commit is relevant to. Without an issue number in the commit message, the commit is simply not taken into account when giving grades.

ניהול וחלוקת משימות, Issues בהקמת פרויקט צריך בשלב הראשון להגדיר מה צריך לעשות מה ה – Features של הפרויקט שיתוף פעולה זה בין משתתפי הפרויקט מתבצע ע"י ה – Issues, בשפת גיטהאב. ה – Issues מגדירים את ה – Features ומתארים אותם. כל פרויקט מורכב ממספר איטרציות (Sprint-ים בשפת "פרויקט אג'ילי"). בתחילת כל Sprint מתקיימת ישיבה בפועל של משתתפי הפרויקט שבה מתכננים את הפרויקט, את התכונות והדרישות שלו ומחליטים מה יהיו ה – Features בגרסא הראשונה.

Issues = משימות ה – Features מהווים את משימות הפרויקט. לכל Issue תוצמד תגית (Label) או כמה תגיות. התגיות מאפשרות לבצע חיפוש ממוקד ולדעת אילו Issues משויכים לאותו נושא. כל Issue יטופל ע"י חבר צוות אחד או יותר, והדבר יצוין בגיטהאב ע"י Assignee.

Assignee מטפל\אחראי הנושא סטטוס מספר issue Labels Assignee מטפל\אחראי הנושא

מרעיונות לפעולות בעזרת Issues Issues are often born as a raw idea. The idea evolves by a discussion: Participants make comments. The rolling discussion, eventually leads to the resolution of the issue in several ways: Holding any further unfruitful discussion placing the issue in the backlog, for further consideration sometime Fine tuning the idea into an actionable assigning it to an individual, who eventually closes the issue.

Properties of an issue Number which never changes   Number which never changes Status, which is either open or close Milestone: which can be either missing (no milestone, or backlog), or a specific milestone defined by the user Labels: manager-defined labels Participants Assignee(s) Comments Other (“like” sign etc.)

Documentation: Wiki and Readme As an essential part of Software, The yearly project in Software Engineering requires thorough external documentation. Documentation needs to include the following: An introduction to the project and the purpose behind it The technologies and tools behind it Two complete Installation guides: One for a consumer trying to run your project, another for a developer who wishes to take your code and expend it. What are the prerequisites, the steps and the dependencies required to build the project. Deep, encompassing explanation of each feature of the project: how to use it, what it does, the expected input and output of the code and possible error cases.

Documentation example Spartanizer, an ongoing project headed by Prof. Yossi Gil and selected outstanding students in our department. https://github.com/SpartanRefactoring/Main/wiki

Automatic tools in Github: There are tools that can work automatically on your code in github. Continuous Integration: Travis C.I. for example, can be programmed to build on each commit, send email to the team when something fails, run unit tests and more. Code Coverage: codeCov for example, is a tool that can report how much of the project’s code is covered by tests. In your newly created project repository, go to “settings” -> “Integration and Services” and explore.