Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

0

Share

Download to read offline

August OpenNTF Webinar - Git and GitHub Explained

Download to read offline

When OpenNTF began in 2001, source control was little known and sharing of code via the cloud was limited. Fast forward 20 years and GitHub is the dominant sharing site and git the standard technology for source control.

In this webinar Paul Withers and Jesse Gallagher will:

Demystify git
Explain Branching
Show what makes a high quality repository
How to take advantage of GitHub’s broad functionality
Get that coveted "Verified" badge
Go from source control zero to GitHub hero!

Related Books

Free with a 30 day trial from Scribd

See all

Related Audiobooks

Free with a 30 day trial from Scribd

See all
  • Be the first to like this

August OpenNTF Webinar - Git and GitHub Explained

  1. 1. OPENNTF WEBINARS August 2021 Webinar – Git and GitHub Explained With Paul Withers and Jesse Gallagher
  2. 2. AGENDA • Welcome – Graham Acres • Paul Withers and Jesse Gallagher • Questions – Graham Acres
  3. 3. ASKING QUESTIONS • First Question – Will this be recorded? • Yes, view on YouTube!!! • https://www.youtube.com/user/OpenNTF • Use the Questions Pane in GoToWebinar • We will get to your questions at the end of the webinar • The speakers will respond to your questions verbally • (not in the Questions pane) • Please keep all questions related to the topics that our speakers are discussing!!! • Unrelated Question => post at: • http://openntf.slack.com/
  4. 4. THANKS TO THE OPENNTF SPONSORS • HCL made a contribution to help our organization • Funds these webinars! • Contests like Hackathons • Running the organization • Prominic donates all IT related services • Cloud Hosting for OpenNTF • Infrastructure management for HCL Domino and Atlassian Servers • System Administration for day-to-day operation
  5. 5. THIS IS OUR COMMUNITY • Join us and get involved! • We are all volunteers • No effort is too small • If your idea is bigger than you can do on your own, we can connect you to a team to work on it • Test or help or modify an existing project • Write guides or documentation • Add reviews on projects / stars on Snippets
  6. 6. NEXT WEBINAR • September 23, 2021 • Domino Online Meeting Integration (DOMI) • Paul Withers, Devin Olson, Rocky Oliver • Signup at https://openntf.org/webinars
  7. 7. UPCOMING EVENTS • DNUG – Domino Best Practices – September 7 • https://dnug.de/event/dnug-online-domino-best- practices-domino-notes-v12/ • Collabsphere Online – October 19-21 • https://collabsphere.org/ug/cs2021.nsf/register.html • Engage 2022 – Bruges, Belgium – March 22-23, 2022 • https://engage.ug/
  8. 8. GIT MECHANICS FOR DOMINO DEVS
  9. 9. Source-control system, similar to SVN, Subversion, et al It was created for the Linux kernel, and is now the dominant source-control system "Git" itself is the open-source project and tool, while there are many different servers and hosting services, such as GitHub and Bitbucket WHAT IS GIT?
  10. 10. GIT CONCEPTUAL LAYOUT A A + B A + B + C A + B + C + D A + B + C + D + E + F A + E A + E + F A series of "commits": one or more file changes relative to the previous state A "branch" is a named sequence of commits Creating a new branch ("branching") allows you to make changes based on a given starting point Merging allows (and forces) you to combine the changes from your branch back "main" and "master" are conventional names for the primary branch, but technically all commits are equal
  11. 11. A commit is an individual unit of changes in a repository Select changed files to add to a commit (or portions thereof) Provide a message Styles vary - some use "does X", some use "did X" Don't use "changes since last time", etc. Do include an issue number if that's part of your flow COMMITS
  12. 12. Remotes Think "replicas", with options for partial replication by branch A local repo can have any number of remotes, but usually there's one and it's "origin" Tags Bookmarks for a specific commit, very often corresponding to releases Submodules Related additional Git repos - handy in some cases, but be wary GIT CONCEPTS
  13. 13. Gitflow (GitFlow? git-flow?) A common idiom for handling branching and versioning projects It also has built-in support in GUI apps and in the CLI Git LFS Allows better handling of binary files (images, archives, etc.) Kind of like DAOS Has to be initialized in your local repo for it to understand, though many GUIs can handle this for you automatically GIT EXTENSIONS
  14. 14. Main project page: https://git-scm.com Git Project Tutorial: https://git-scm.com/docs/gittutorial Atlassian Tutorials: https://www.atlassian.com/git/tutorials Gitflow Tutorial: https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow GIT RESOURCES
  15. 15. GIT TOOLS
  16. 16. Git is command-line-first, but this is very daunting in general, and particularly for someone new These GUIs usually wrap the official CLI commands, but expose options in a more-intuitive way They tend to make it much easier to visualize the history, get an overview of the repository, and generally do work Some support extended features, such as managing GitHub Pull Request inline GUI APPLICATIONS
  17. 17. Many tools, free and non-free, exist: SourceTree from Atlassian: https://www.sourcetreeapp.com/ NotesIn9: https://www.youtube.com/watch?v=TivgBeOHcEo GitHub Desktop: https://desktop.github.com/ Tower (the one I use currently): https://www.git-tower.com/ Git project's list: https://git-scm.com/downloads/guis GUI APPLICATIONS
  18. 18. GUI APPLICATIONS
  19. 19. Git can work over several protocols, with the two dominant ones being HTTPS and SSH Many Git hosts allow or require SSH use to access, including GitHub This is fiddly in all cases, but particularly so on Windows Sorry ¯_(ツ)_/¯ Setup generally involves creating an SSH keypair locally and then pasting the public key into the web GUI for your host GitHub tutorial: https://docs.github.com/en/github/authenticating-to-github/connecting-to-github- with-ssh SSH
  20. 20. WORKING WITH AN NSF
  21. 21. Designer can sync an NSF with an On-Disk Project (ODP) This project contains all design elements exported as DXL Some elements, like image resources and XPages, are split in a useful way Designer uses the term "Team Development" to refer to its NSF<->ODP sync Use "Build Automatically" or explicitly build apps DESIGNER
  22. 22. "Binary DXL" An option in Designer prefs, applying to all databases This DXL format is less friendly (no HTML-like form bodies, etc.) but is safer for true round-trip use Though it makes collaboration more difficult, the safety is worth it Put the ODP in a sub-folder of the repo ...and maybe in an "odp" sub-folder of that This avoids importing Git metadata into the NSF and will help when the project grows DESIGNER TIPS
  23. 23. Swiper removes unnecessary and frequently-changing data from exported design elements Time last signed, etc. While not explicitly mandatory, it may as well be This is installed in Designer and can be configured to apply automatically to all source-control operations ...which it should be SWIPER
  24. 24. A project of mine used to integrate ODPs with automated builds Not required for source control, but can be useful particularly when working with OSGi plugins or multiple ODPs in one repo CollabSphere presentation: https://www.youtube.com/watch?v=7MeCMz0F-vM NSF ODP TOOLING (OPTIONAL)
  25. 25. Official documentation: https://help.hcltechsw.com/dom_designer/9.0.1/user/wpd_srcecontrol_feature_setup.html NotesIn9: https://www.youtube.com/watch?v=wl_6LCkopMI https://www.youtube.com/watch?v=I4nA0aksMJA https://www.youtube.com/watch?v=kjpM3NolEiA DESIGNER TUTORIALS
  26. 26. GITHUB-ISMS
  27. 27. Forking allows you to create a full copy - code, commit history, etc. - of a repository in your profile or organization Forks maintain a loose relationship with the original repository, with options to bring in changes from the original GitHub recently added "Fetch Upstream" to make this easier This can be used to either create a wholly-new entity or to work on changes that you then send back "upstream" Technically, they're two distinct Git repositories protocol-wise FORKED REPOSITORIES
  28. 28. "Pull Request" means that you want to make a request to a repository owner/manager to merge in changes you've made These changes can either be in a branch in the same repository or in a forked repository This allows for multiple types of collaborative workflows: many authors in distinct branches in one repo, or each author with a forked repo The request includes all commits in your branch that are not present in the destination branch This pairs well with Gitflow, where you request a merge of a feature branch PULL REQUESTS
  29. 29. IP MANAGEMENT
  30. 30. LICENSE file License compatibility NOTICE file List all third-party code, even if it's just from a blog post Optionally, license headers BASICS
  31. 31. Choose your license (safest bet is Apache) and copy the license into your repo GitHub can add a license file for you when creating a new repository Make sure to set the copyright year and owner in the file if applicable! Make sure all your included dependencies are compatible In general, there are "permissive" and "copyleft" open-source licenses "Permissive" is more "business-friendly" in many cases You can mix GPL code in with others (often), but then your code must be GPL LICENSE FILE
  32. 32. Enumerate all included code, both code copied into the source repository and code included in any final distribution package If third-party code contains its own NOTICE file, copy that into your repo, e.g. "NOTICE-apache.txt" Mention in your notice if you don't use all of those dependencies, but keep their file intact Check many projects under the OpenNTF GitHub org for examples Guide for Apache-foundation projects: https://infra.apache.org/licensing-howto.html NOTICE FILE
  33. 33. GPL/LGPL Code Stack Overflow code Be very careful! Snippets are okay, but larger blocks must be specially licensed from the author for proprietary works Blog Posts Unless the page has an explicit code license, it must be considered proprietary until you get permission from the author As a general rule, author permission is your escape hatch, as it's effectively re-licensing it COMMON TRAPS
  34. 34. GitHub Explained Paul Withers
  35. 35. Repository Files README.md – your “landing page” LICENSE – text will be standard for the license type NOTICE – lists license and copyright info for third party code used CONTRIBUTING.md – do you accept contributions? What do people need to know, to make your life easier? CODE_OF_CONDUCT – makes explicit expectation for all involved AUTHORS – optional, some projects use this to track who has contributed .github/ISSUE_TEMPLATE – issue template templates, to ensure people give you the information you need to solve their issues? .github/pull_request_template.md – pull request template, to ensure all involved do what you need
  36. 36. README Some Things to Think About • Badges? • What is the purpose of the project? • What requirements or pre-requisites are there for using it? • Software versions? • How to get it working • How to build a development environment • Link to documentation – suggestion: GitHub Pages • Contributing • Acknowledgements • License statement • Disclaimer
  37. 37. License • Preferred license is Apache 2.0 • Greatest flexibility, MIT is very similar • License will depend on third-party resources included • Licensing can affect images as well as code • If in doubt, ask • Copyleft (GPL variants) can require same license • Copyleft require circulation of source code • Not a problem for the open source project • But can limit how others use the project • https://choosealicense.com/licenses/ has details of what licenses allow • NOTE: Remember to update copyright date and name
  38. 38. Copyright Headers Short boilerplate of license, author and copyright Added to code files, where appropriate Some files won’t work if front-matter is added Avoids confusion if code is used out-of- context
  39. 39. NOTICE • Start with this project name and copyright • For each third-party code, include • Name of the project • Link to the source • Copyright details
  40. 40. Contributing If you’re not accepting contributions, it’s helpful to say so Can be a way to build a community around the project Do you want an issue before a PR? Do you want PR process for very small changes? Development environment setup Are there style guidelines to ensure consistent formatting? Include settings files and preferences Expectations for testing locally All contributors will have to sign CLA (Contributor License Agreement)
  41. 41. Other Files • Provides a single point-of- reference for everyone involved • CONTRIBUTING / PR template can tell contributors to add their name AUTHORS • List of changes for each release CHANGELOG
  42. 42. Issue Templates / Pull Request Templates • Prompt for information you need (version, OS, browser etc) • Steps to reproduce • Logs • Prevent misuse • Exclude feature requests for features that will remain out of scope • Can be autoclosed by GitHub functionality Issue Template • Prompt for link to a GitHub issue • Prompt for actions to be performed (e.g. updating AUTHORS) • Remind committers of actions Pull Request Template
  43. 43. Additional Info Ensure a LICENSE file is included Click ”cog” next to About on repo Add a description Add one or more topics GitHub automatically determines primary language
  44. 44. Other GitHub Functionality Discussions allows more flexible communication with community Projects allows management of work on issues GitHub Pages more extensive online documentation Actions can provide automation
  45. 45. GitHub Pages • Can be run locally – Ruby, Jekyll, Bundler • Can be previewed on HCL-internal repo • Uses (GitHub-flavoured) markdown • https://guides.github.com/features/mastering- markdown/ • Use relative links • Don’t map to the .md file • Liquid filters (https://jekyllrb.com/docs/liquid/filters/) • Jekyll-relative-links plugin? https://nicolas- van.github.io/easy-markdown-to-github-pages/ • In-built themes are available • Just the Docs is another theme that can be used https://pmarsceill.github.io/just-the-docs/
  46. 46. Dependabot and Security Settings > Security and analysis Can enable alerts for vulnerabilities from Dependabot Enabling “Dependabot security updates” automatically generates PRs (if possible) to fix security issues
  47. 47. GPG Signature Adding a GPG signature to GitHub verifies your commits Gives an extra mark of quality GPG Suite for Mac or Gpg4win for Windows from GnuPG Create a signing key Tell Git about your key Add public key to GitHub Passphrase can be stored in Mac OS Keychain but expires after an hour on Windows
  48. 48. Questions
  49. 49. QUESTIONS? Use the GoToWebinar Questions Pane Please keep all questions related to the topics that our speakers are discussing!!! Unrelated Question => post at: http://openntf.slack.com/

When OpenNTF began in 2001, source control was little known and sharing of code via the cloud was limited. Fast forward 20 years and GitHub is the dominant sharing site and git the standard technology for source control. In this webinar Paul Withers and Jesse Gallagher will: Demystify git Explain Branching Show what makes a high quality repository How to take advantage of GitHub’s broad functionality Get that coveted "Verified" badge Go from source control zero to GitHub hero!

Views

Total views

126

On Slideshare

0

From embeds

0

Number of embeds

0

Actions

Downloads

10

Shares

0

Comments

0

Likes

0

×