class: center, middle .logo[] _January 28th, 2019_ ### Recitation ## Version control and Project management **Fiore Basile** [fiore.basile@gmail.com](mailto:fiore.basile@gmail.com) .logo_tiny[  ] --- class: left, top # About me - Working on software since 1993 - Graduated [Fab Academy 2014](http://archive.fabacademy.org/2014/students/basile.fiore/), since then global evaluator and staff - [Fab Lab Cascina](https://fablabs.io/fablabcascina.org) (RIP), [Fab Lab Toscana](http://fablabtoscana.it) regional network - Setup labs around the world - Projects for the Fab Lab network: - [Academany](http://academany.org), [Nueval](http://nueval.fabacademy.org), [Fab Jobs](http://jobs.fabeconomy.com), [Fab Event app](https://app.fabevent.org), [fablabs.io](https://fablabs.io), .. - Co-founded - [Fabricademy: a new Textile Academy](https://textile-academy.org) - [fabctory](http://fabctory.com) - Workshops and interactive installations: - [Made in a Fab lab](https://fablabmade.com) - [Giant Arduino](https://twitter.com/arduino/status/1050005880073273344) --- class: center, middle <blockquote class="twitter-tweet" data-lang="it"><p lang="en" dir="ltr">"Honey, I shrunk David!" <a href="https://t.co/X6UfX8mwtb">pic.twitter.com/X6UfX8mwtb</a></p>— Arduino (@arduino) <a href="https://twitter.com/arduino/status/1050005880073273344?ref_src=twsrc%5Etfw">10 ottobre 2018</a></blockquote> --- class: left, top # Topics ## - [Version control](#chapter-version-control) ## - [Fab Cloud platform](#chapter-gitlab) ## - [Project management](#chapter-project-management) ## - [Documentation](#chapter-documentation) --- class: left, top background-image: url(images/versioncontrol.png) name: chapter-version-control # Version Control --- layout: true **VERSION CONTROL** --- ## What is version control? Tracking every change in a set of files .small-img[  ] Useful for collaboration, backups, reverting and merging changes made by different people ??? Version control is a requirement when many different people work together. But also for personal projects with a minimum of complexity. You want to learn version control if you want to contribute to any open-source project. When doing version control we associate a state of our files in the current moment with a label and a timestamp. This way we can build up a project repeating those changes over a common archive. --- <img src="images/git.png" style="width:200px"/> - We use [GIT](https://git-scm.com/), a software built by Linus Torvalds to manage the Linux kernel source files. - GIT can be used to track any kind file (\*) - Can work locally and can talk to a remote server for exchanging files and versions .center[ .small-img[  ]] .footnote[(\*) Large files should be stored using [GIT LFS](https://git-lfs.github.com/) (Large file storage).] --- ## Mastering GIT Learn key concepts: - Repository - Commit - Branches - Pulling and pushing, merging, rebasing - Pull requests - Tags Key is **PRACTICE**, so Get started with a GUI client, but try the command line for GIT superpowers. ??? To make the most out of GIT you should learn a few key concepts You can start with few commands, the most advanced ones you will learn when you need --- ## Ways to use Git - Command line on [Mac](https://brew.sh/), [Linux](https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-18-04), [Windows](https://git-scm.com/download/win) ```bash $ cd yourproject/ $ git init $ git add README.md $ git commit -m 'welcome to git' ``` - Client application ex. [Github client](https://desktop.github.com/), [Tower](https://www.git-tower.com/mac), etc. - Text editor, [Atom](https://atom.io/), [Visual Studio Code](https://code.visualstudio.com/), [Eclpise](https://www.eclipse.org/) - Web interface like Github or [Gitlab](https://gitlab.fabcloud.org) - In another software as a [library](https://libgit2.org/) --- [Git-it](https://github.com/jlord/git-it-electron#what-to-install) is a Desktop app that teaches how to use Git and Github. 99% of what you will learn can be used on Gitlab too. .small-img[  ] ??? Git-it is like a wizard that guides you in the process of setting up git on your computer and run basic examples exploring git features It was made by Github, but it's not Github specific --- ## Past Recitations Available in [Fabacademy 2018](http://fabacademy.org/2018/) archive: - **Version Control**: Covers GIT command line and lots of details on Version control: Slides: [http://fabacademy.org/2018/recitations/version-control.html](http://fabacademy.org/2018/recitations/version-control.html) Video: [https://vimeo.com/252229788](https://vimeo.com/252229788) - **Gitlab**: Provides more details on the gitlab platform and services Slides: [http://fabacademy.org/2018/recitations/gitlab.html](http://fabacademy.org/2018/recitations/gitlab.html) Video: [https://vimeo.com/253336757](https://vimeo.com/253336757) --- layout: true --- class: center, middle name: chapter-gitlab # Fabcloud platform <img src="images/fabcloud_logo.png" style="width: 300px"> --- layout: true **FABCLOUD** --- ## What is FabCloud Online services for the Fab Lab Network ### Goals - Collect all projects in a single place - Host the Fab Lab Network's websites - Provide a tool for collaboration and communication between labs - Any lab and individual can use it for projects and websites also outside Fab Academy - Register new accounts using [fablabs.io](http://fablabs.io) --- #### https://gitlab.fabcloud.org - All **Fab Academy Students** have been **pre-registered** ##### Login with your email address as username and student_id as password.  --- layout: true **GITLAB** --- ## Gitlab & FabAcademy We use GitLab for all the content related to Fab Academy. #### What we do with Gitlab 1. Keep all student files under [version control](http://fabacademy.org/2018/recitations/version-control.html) 1. Track [groups](https://gitlab.fabcloud.org/academany/fabacademy/2019/) of students, labs, instructors and staff 1. Publish the FabAcademy [site](http://fabacademy.org/2019) 1. Publish and host [lab](http://fabacademy.org/2019/labs.html) and [student](http://fabacademy.org/2019/people.html) pages 1. Publish documents like the [Fab Academy Handbook](http://fabacademy.org/2019/docs/FabAcademy-Handbook/) 1. Discuss class [issues](https://gitlab.fabcloud.org/academany/fabacademy/2019/class/issues) 1. Take meeting notes using [Markdown](https://docs.gitlab.com/ee/user/markdown.html) [syntax](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md) 1. Build personal sites and documentation using [static site generators](http://www.staticgen.com) --- layout:true .responsive-img[  ] --- ### Get started with Gitlab - Setup your profile, notification settings - Create local repositories for software or websites. - Use Gitlab to create documentation and notes - Use personal projects on Gitlab to sync your local repositories. - Use Gitlab as a project management tool --- layout: true **ACCOUNT SETUP** --- ### Setup you profile <div style="width: 100px; float: right; margin-right: 150px; margin-top: -100px"> <img src="images/settings.png"> </div> - Login to Gitlab, click on the upper right icon and Settings - You can add a secondary email address - You can set your [avatar image](http://gravatar.com) and add some more info about you #### WARNING: Don't change your username or email, or bad things will happen --- ### Notifications settings You have global settings in the account page: .bordered[  ] ??? TIP: Check the _Receive notifications about your own activity_ flag to confirm you receive notifications, then open a ticket to yourself --- ### TIP: Enabling notifications for the Fab Academy Class project You can also configure notifications _selectively_ in each project's dashboard. - Go to the [Class](https://gitlab.fabcloud.org/academany/fabacademy/2019/class) project on FabCloud - Click on Notifications and set this project setting to **Watch**. ??? **Follow these instructions or you won't receive important messages about the class** --- ## SSH Keys Git uses the SSH protocol to establish secure communication between your computer and the GIT server hosting your repository. This makes sure only you can update your repository and nobody else can tamper the communication. **Without SSH Key you can only use the web interface**. SSH Keys allow you to use the GIT repository securely, without requiring a password every time. #### Generate your [SSH Key](https://docs.gitlab.com/ce/ssh/README.html#generating-a-new-ssh-key-pair) - Linux and MacOS ```terminal ssh-keygen -t rsa -C "your.email@example.com" -b 4096 ``` - Windows [Using PuttyGEN](https://the.earth.li/~sgtatham/putty/0.67/htmldoc/Chapter8.html#pubkey-puttygen) --- ### Add the public key to your authorized keys .full-width[] --- layout: true --- class: center, middle name: chapter-projectmanagement # Project management ??? How to organize and manage a project on Fabcloud. How to use issue trackers and kanban boards for project management How to use the repository as a project storage space. --- layout: true **PROJECT MANAGEMENT** --- ## Creating a project You can [create](https://gitlab.fabcloud.org/projects/new) as many projects as you want: - A new empty project - Importing a project from an existing Git repository - Forking a project from someone else --- ## Files - The **web interface** makes it easy to interact with the repository, i.e. Google drive. - You have a good preview of **Markdown** content - A file called **README.md** in the root of each project folder will be shown as default file. **TIPS** - To **create an empty folder**, you should upload an (empty) file called `.gitkeep` - To **replace** a file you need to upload one with the **same name** - **Save often** when editing files using the web interface - **Clone the files locally** and use GIT, it makes life much easier in the long run --- ## Issue trackers - Gitlab allows to track todo items using Issue trackers - For each project you have access to, you can browse and create issues: .center[.full-width[]] --- ## Using issues - Communicate with the class / Replacing emails - Track your personal tasks (in your projects) - Use them as kanban boards - Assign issues to milestones .center[.full-width[]] --- ## Issues vs Email - **Threaded conversations**, so you can catch up quickly and find discussions easily - **Reply using issues**. Click on the **link in the footer** of the email! - **No spam.** Keep the conversation relevant - Everybody will still receive email notifications, **use with care** - **Close issues **when they are complete --- ## Kanban boards - You can use issues for creating Kanban boards, similar to [Trello](http://trello.com) - [Kanban boards](https://en.wikipedia.org/wiki/Kanban_board) were invented by Toyota for car manufacturing - One look to see how work progresses i.e. from todo, to doing, to done - Click on **Issues > Boards** to see and arrange your issues as a Kanban board - [Pomodoro Technique](https://en.wikipedia.org/wiki/Pomodoro_Technique), [GTD](https://en.wikipedia.org/wiki/Getting_Things_Done) --- **Workflow tracking** .responsive-img[  ] --- **Team contributions** .responsive-img[  ] --- ## Milestones Another way to organize your work, is to group issues into [Milestones](https://docs.gitlab.com/ee/user/project/milestones/) - Each **milestone** represents an **important step** in your project - **Assign issues to a Milestone**, when all are completed you reached your Milestone - Easy to distinguish more urgent work from what can be done later - You can assign **start and end dates** to each milesone - Milestone help spiral development, and meeting deadlines! --- ## Agile project management - Break down your project objectives into a roadmap - Break down roadmap into milestones - Break down each milestone into set of issues - epics - Sort issues by priority / time available - Break issues into ones that you can do in one go - stories --- ## Wikis - Gitlab also provides a [Wiki](https://en.wikipedia.org/wiki/Wiki) for each project - Wikis are a one way to write the documentation for a software or hardware project - Wikis use Markdown, but allow for easy [hyperlinking](https://gitlab.fabcloud.org/help/user/markdown#wiki-specific-markdown) - To create a new page, add a link: ``` [Title](pagename) ``` Save and click on it. We expect you to learn HTML and publish a public site, but you can keep your notes during class on a wiki in your personal project. --- ## Gitlab API Gitlab offers a [rich API](https://docs.gitlab.com/ee/api/README.html) (application programming interface) for accessing most of the features available via GUI. **What you can do with the API?** - Query your groups and projects - Upload / Edit files - Open issues - Check your repo size - Start CI jobs - ... almost anything you can do with the GUI --- ## Using the API - Get your [Personal API Token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) - Pass it to API calls ```terminal curl --header "Private-Token: SpdRM-dN4xsCGGrcZQRR" \ https://gitlab.fabcloud.org/api/v4/projects ``` You will get a JSON ```json [ { "id": 713, "description": "", "name": "my-great-project", "name_with_namespace": "fibasile / my-great-project", "path": "my-great-project", ... ``` --- ## Access API from Python Install the [Python API Wrapper](https://github.com/python-gitlab/python-gitlab) ```python import gitlab gl = gitlab.Gitlab('https://gitlab.fabcloud.org', private_token='SpdRM-dN4xsCGGrcZQRR') # list all the projects projects = gl.projects.list() for project in projects: print(project) # list all project issues issues = project.issues.list() # Filter using the state, labels and milestone parameters issues = project.issues.list(milestone='1.0', state='opened') # Order using the order_by and sort parameters issues = project.issues.list(order_by='created_at', sort='desc') ``` Check the [Docs](https://docs.gitlab.com/ee/api/README.html) for more examples --- layout: true --- class: center-middle name: chapter-documentation # Documentation ??? Use static site generators to document projects --- layout: true **DOCUMENTATION** --- ## GitLab CI One of the killer features of Gitlab. CI stands for [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) a common practice of software development. What this is capable of: - Compiling websites with static site generators - Make beautiful documentation using Gitbook, Sphinx, Mkdocs - Automated Testing for software - Resizing images - Integrating content from different sources - ...much more --- ## Website Publishing Using gitlab you can publish content that will be served via Web. - Your student website, find the link in the [students list](http://fabacademy.org/2018/students.html) - Your personal website, create a project named `<username>.fabcloud.io`, and browse it ```terminal http://<username>.fabcloud.io ``` - Any other personal project, the address will be ```terminal http://<username>.fabcloud.io/<project_name> ``` --- ## How to publish your website Publishing your website is done using [Gitlab CI](https://docs.gitlab.com/ee/ci/quick_start/) 1. You create a [gitlab-ci.yml](https://gitlab.fabcloud.org/academany/fabacademy/2018/labs/barcelona/students/student-name/blob/master/.gitlab-ci.yml) file of type HTML 2. You upload a [static webpage](https://en.wikipedia.org/wiki/Static_web_page) 3. Every time you update any file in your projects (using git or the web interface) your website will be updated\* (\*) updates are almost immediate, but not realtime --- ## How does it work? - Using [Docker](https://www.docker.com/) - GitLab CI allows to start a virtual server - install software on it - and execute it for performing one or more tasks - storing results and publishing them on the web This process is described by the **gitlab-ci.yml** file you create into a folder --- ## Build process .center[.full-width[]] --- ## Pipelines Each time this happen we are running a **Pipeline** on a **Runner** .center[.full-width[]] You can monitor pipelines in the [Gitlab CI Menu](https://gitlab.fabcloud.org/academany/fabacademy/2018/labs/barcelona/students/student-name/pipelines) --- ## Building websites with Jekyll Using Gitlab CI you can make your website using a [static site generator](http://staticgen.com) ### Clone my project - [Jekyll Project](https://gitlab.fabcloud.org/fibasile/jekyll) - [Demo](http://fibasile.fabcloud.io/jekyll/) --- ## Run jekyll Locally Install [Jekyll](http://jekyllrb.com). 1. Install [RubyGems](https://rubygems.org/pages/download) 2. Run the following to install jekyll and serve the site locally ```terminal $ gem install jekyll bundler $ jekyll new mysite $ cd mysite $ jekyll serve ``` then browse to http://localhost:4000 3. Add your repository as remote, and push the content of _mysite_ to gitlab 4. Create [a .gitlab-ci.yml using the Jekyll template](https://docs.gitlab.com/ee/user/project/pages/getting_started_part_four.html) --- ## .gitlab-ci.yml for jekyll ```yaml image: ruby:2.3. ## use docker ruby version 2.3 image variables: JEKYLL_ENV: production ## tell jekyll to make a production build cache: paths: ## keep a cache of vendor/ - vendor/ ## path for faster build before_script: - bundle install --path vendor ## install jekyll and deps in vendor pages: script: - bundle exec jekyll build -d public ## run jekyll with output in public/ artifacts: paths: - public ## keep and store the results in public/ only: - master ## work only on master branch ``` NOTE: Don't copy text after #, this is a comment --- ## Building documentation Another common use of Gitlab-CI is to build documents using Markdown. This can be done using several software packages. - [Mkdocs](https://mkdocs.org) - [Gitbook Toolchain](https://toolchain.gitbook.com/) - [Sphinx](http://www.sphinx-doc.org/en/master/) --- layout: true **DOCUMENTATION** ### Mkdocs --- - Framework used to build the student documentation page - Great themes (Mkdocs-bootswatch, Mkdocs-material) - Only one 'mkdocs.yml' config file - The content should be in a folder called `docs` ### Getting started This example uses python [virtualenv](https://virtualenv.pypa.io/en/latest/) **Replace with your repo url** ```bash # replace the address below with your repo url git clone git@gitlab.fabcloud.org:fibasile/mkdocs.git cd mkdocs virtualenv .env source .env/bin/activate pip install -r requirements.txt mkdocs serve ``` --- ### Gitlab CI The project contains a preconfigured `.gitlab-ci.yml` ready to use Mkdocs. Every time you push a change the site is rebuilt. ### Configuration Get the standard configuration options from [the configuration help page](https://www.mkdocs.org/user-guide/configuration/) Add theme specific configuration, for example [Mkdocs Material](https://github.com/squidfunk/mkdocs-material/blob/master/docs/getting-started.md#configuration) --- layout: true **DOCUMENTATION** --- ## Gitbook Gitbook allows to generate: - A **web-ready** version of your book - A **PDF** version - A **mobi/epub** version for e-book readers All from the same source files. --- ## How to create a gitbook 1. Create a new project / repository i.e. `my-book-project` 2. Install [Gitbook CLI](https://toolchain.gitbook.com/) ```terminal $ npm install -g gitbook-cli ``` 3. Setup an empty book using the terminal ```terminal $ mkdir my-book-project $ cd my-book-project $ gitbook init Installing GitBook 3.2.3 ... ``` 4. Edit your book - Edit the contents of `README.md`, the book's cover page - Create new files in [Gitbook Markdown](https://toolchain.gitbook.com/syntax/markdown.html) - And add a link to them into the `SUMMARY.md`, the book's index --- ## How to build a gitbook 4. Test your book using ```terminal $ gitbook build ``` and opening the generated `index.html` in the `_book/` folder 5. Add a `.gitignore` file containing `_book/` into your folder, so you commit just the source 6. Push the folder in Gitlab, and add the Gitbook [.gitlab-ci.yml](https://gitlab.fabcloud.org/academany/fabacademy/2018/docs/FabAcademy-Handbook/blob/master/.gitlab-ci.yml) 7. Browse your generated gitbook at `http://<youruser>.fabcloud.io/my-book-project` 8. Download the PDF version of your book `http://<youruser>.fabcloud.io/my-book-project/book.pdf` --- layout: true --- class: center, middle name: chapter-project-management # Credits and references --- name: refs ## References #### GIT - [Git - Book](https://git-scm.com/book/en/v2) - [NDP Software :: Git Cheatsheet](https://ndpsoftware.com/git-cheatsheet.html) - [Try GIT](https://try.github.io/) - [Take Your Git Practice To The Next Level](http://batmat.github.io/presentations/git-next-level/prez.html) - [Introduction to GIT LFS](https://www.youtube.com/watch?v=uLR1RNqJ1Mw) #### Gitlab - [Gitlab Documentation](https://docs.gitlab.com/) - [Gitlab Markdown](https://docs.gitlab.com/ee/user/markdown.html) - [Gitlab API Docs](https://docs.gitlab.com/ee/api/README.html) - [Python API wrapper Docs](http://python-gitlab.readthedocs.io/en/stable/) - [Gitlab CI](https://docs.gitlab.com/ee/ci/yaml/README.html) - [4 Ways to use Gitlab Kab Ban Boards](https://about.gitlab.com/2018/08/02/4-ways-to-use-gitlab-issue-boards/) --- #### Static site generators - [staticgen directory](https://www.staticgen.com/) - [mkdocs](https://mkdocs.org) - [awesome markdown](https://github.com/mundimark/awesome-markdown) - [vuepress](https://vuepress.vuejs.org) - [gatsby](https://www.gatsbyjs.org/) #### Project management - [Agile Project Management](https://www.atlassian.com/agile/project-management), see also Epics, User Stories - [Trac](https://trac.edgewall.org/) wiki and issue tracking - [Redmine](https://www.redmine.org/) for software projects - [OpenProject](https://www.openproject.org/) an advanced open source PM software --- ## Credits ### Images from ProGIT Book This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.