Using GitHub means embracing GitHub culture. One of the main goals of using a VCS like GitHub is to facilitate open contribution, one of the four freedoms (the Freedom to Contribute) of the Libre Fonts movement.
When working on an open platform like GitHub, development should happen publicly, ideally from day one, allowing others to view work in progress, and enabling the public to point out issues during development instead of after the typical 1.0 release.
Early feedback and contributions are some of the most valuable assets of open-source culture, as having multiple eyes on the project’s development leads to better tested and, therefore more robust projects.
At ATypI 2014 David Lemon, the senior manager of the Adobe Type group, discussed how the Adobe Type team has benefited from libre fonts culture and said that Git and Github were some of the most positive aspects. Adobe used the “publish early and often, gathering feedback” approach of Libre projects in its Vortice typeface project.
The first step is to create a GitHub account. This is done similarly to any other cloud service by providing basic information: name, user name, and password.
Be sure to use a valid email as it is used to sign every commit (interaction) that you have with the platform. You also receive GitHub notifications from your repositories to that email account.
Once you have an account, you need to create authentication keys to be able to interact with the platform.
When you work with GitHub, you will work in a local clone of a repository (a Git project folder on your computer), which you will frequently sync with the connected remote repository on GitHub.
There are two protocols used to connect to and interact with GitHub repositories: HTTPS and SSH, and each of them requires a different form of authentication to GitHub.
When performing Git operations over the HTTPS protocol, Git prompts you for a username and password every time you try to interact with GitHub. In those cases, a Personal Access Token (PAT) is used in place of a password for authentication to GitHub (e.g. when cloning repositories using HTTPS), so you would need to create a PAT.
You can avoid being prompted for your token and enter it manually each time you interact with GitHub by configuring Git to cache your credentials for you.
Once you have created the PAT, you must configure it as part of your environment variables to work properly with GitHub, by saving it in your .bash_profile like this:
GH_TOKEN=YOUR_CREATED_PERSONAL_TOKEN
Where the value after the = corresponds to your created personal token. Please keep in mind that your token is private. Keep it safe, and never share it publicly.
When working with GitHub using the Secure Shell Protocol (SSH), you need to first check for existing SSH keys or, if you don’t have one, you would need to generate a new SSH key and add it to your GitHub account before it can be used to authenticate. With an SSH key, you can connect to GitHub without supplying a username and PAT at each interaction.
To avoid reentering your passphrase each time you use the SSH Key, you must add your key to the SSH agent.
Don’t hesitate to search the Internet for how to install the SSH key properly according to your chosen environment, as it is different depending on your OS and software.
A repository (or “repo”) is a place to save the project’s files and work history, allowing you to share, review and track the project’s development.
Both new repos and forked ones will be located in your GitHub account, and they are called the remote repositories because the “source” of the repository is hosted remotely on GitHub.
The forked repo will be the origin remote location, while the source repo will be upstream remote location.
After you have created or forked a repo, you will need to clone the repository to have a local copy on your computer so that you can access, edit, and later sync the files between locations.
Having the repository hosted remotely allows you to keep different copies of the same files that could be at different stages of development, and this also allows for multiple collaborators to be working on the same project in a planned and synchronized way.
When working with source projects on GitHub, it’s common to have multiple forks of the same project, each owned by different users. Each contributor works on their own fork, periodically contributing their changes to the upstream repository. Therefore, it is crucial to work organized and coordinated, but GitHub helps you to achieve that.
→ Create and name your repository
If you are a foundry or collaborative project:
→ Repositories vs. cloud syncing
If you are used to keeping design work synced to Dropbox, Google Drive, or iCloud, it is strongly advised you exclude your Git repos folder from this type of cloud syncing. If you start a project inside a cloud-synced area, then move that work into your git-repos area, make sure the syncing doesn’t follow your content. General-purpose cloud syncing and Git have different purposes and can interfere with one another in strange ways.
Git detects which files have been changed. It allows you to be aware of those changes and register them in an organized way using commits.
Commits are often referred to as a snapshot of the current changes and are a mechanism to make a labeled record of each step of the development. Registering these snapshots also makes it possible to roll back changes and return to a previous state of development if needed; this is the key concept of working with Git.
I used to hate Git because I didn’t understand why I had to use it… until I started working with agile methods. Since then, I’ve kept using Git even on projects that I work on alone because the commit messages help me remember things I did and why I did them on each project.
As well as making frequent commits, it is also suggested that you frequently push and pull the job done. Pushing means publishing the commits you have made locally to GitHub; making them visible to other contributors and visitors to the repository site. Conversely, pulling means integrating the changes made by others into your local work. Pushing and pulling is how you synchronize the copy of the repository on your computer with the remote origin hosted on GitHub.
What happens if you work on your project, but others have also worked on it in the meantime and pushed their changes? If multiple people have worked on exactly the same part of a file, then it is possible for the changes to conflict. Git is very good at working out the best way to resolve conflicts and integrate multiple sets of changes together, but the structure of font source files tends to make conflicts more likely.
Because of the above, it’s a good practice to
Pull Requests (PRs) allow changes to a project to be merged into another project location (whether it is the remote upstream location or the fork origin). Typically, someone who wishes to contribute a change to a project will make a new branch in the origin repo, where they make the change, and then request that this branch be “pulled” into the upstream repo.
If a contributor has writing access to a repository, it is possible to skip the forking step and commit to a branch (often called dev) on the original project that can be later merged to the main branch. However, different projects have different workflows, so check what other contributors are doing to follow it, avoiding creating conflicts.
If you run into a bug, question, or have a feature request for a project on GitHub, you can file an Issue on that repo to alert the owners and get help.
Check out the complete Github’s documentation about issues to know more about them.
Continuous Integration was originally defined as the process of merging the work of all developers of a project into the main source code repository regularly, up to several times per day. However, the term is mainly used for automated code testing and analyses, which are activated whenever a code merge occurs.
GitHub Actions allow automated actions to be run when specified things happen in the repository. For example, a repository containing a software project might define an Action that is run each time a new PR is made, which runs the project’s test suite.
Our Google Fonts project template, recommended as a starting point for font repositories, defines some GitHub Actions that runs every time you push your changes to GitHub.
Using GitHub Actions means that you can always get an up-to-date view of your fonts and their readiness for production, relying on Google Font’s latest versions of build tools.
If you are not using our template, it is strongly suggested that you include at least a Build & Test action to check the building process is running ok to produce the fonts and test the resulting fonts with Fontbakery each time you push a change into a source file. Here is an example of that action.
You can also set git to use your preferred code editor for all git commit messages and similar.
If you are a Visual Studio Code user, run:
git config --global core.editor "code --wait"
If you are an Atom user, run:
git config --global core.editor "atom --wait"
Git on Mac
On Mac OS X, the filesystem is “case insensitive,” which means these two file names access the same file data:
Montserrat-SemiBold.ttf
montserrat-semibold.ttf
This often causes problems when renaming files. To configure git to be case-sensitive, run:
git config core.ignorecase false