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!
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/
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
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
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
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)
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
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
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/
