August OpenNTF Webinar - Git and GitHub Explained
•
0 likes•265 views
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!
Report
Share
August OpenNTF Webinar - Git and GitHub Explained
- 1. OPENNTF WEBINARS August 2021 Webinar – Git and GitHub Explained With Paul Withers and Jesse Gallagher
- 2. AGENDA • Welcome – Graham Acres • Paul Withers and Jesse Gallagher • Questions – Graham Acres
- 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. 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. 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. NEXT WEBINAR • September 23, 2021 • Domino Online Meeting Integration (DOMI) • Paul Withers, Devin Olson, Rocky Oliver • Signup at https://openntf.org/webinars
- 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. GIT MECHANICS FOR DOMINO DEVS
- 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. 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. 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. 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. 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. 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. GIT TOOLS
- 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. 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. GUI APPLICATIONS
- 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. WORKING WITH AN NSF
- 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. "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. 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. 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)
- 26. GITHUB-ISMS
- 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. "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. IP MANAGEMENT
- 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. 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. 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. 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
- 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. Questions
- 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/