This guide walks through the steps for publishing a new Aras Community Project to GitHub, from installing Git to pushing your code to GitHub. If you are looking for other information on Aras Community Projects, like best practices or how to contribute to an existing project, you can check out these resources:
- Aras Community Projects page
- Aras Community Projects 101
- Best Practices, Part 1
- Best Practices, Part 2
- Submission Guidelines
- Project Submission Form
If you are brand new to using Git or GitHub for version control, there are a few setup steps you’ll need to perform to follow along with this tutorial. If you already use Git on your machine and you already have a GitHub account, you can skip to the next section: Create Your Local Repository.
The official Git documentation includes install instructions for Linux, Mac, and Windows. I would recommend installing Git via the installer for your operating system rather than the “Install from Source” option.
Choose Your Git Client
A GUI client isn’t required to use Git for version control, but it can certainly make the experience more pleasant. The alternative is to use the Git command in command prompt. For this tutorial I’ll be using my favorite Git client, GitKraken. I’ll also include the Git commands for anyone following along in command prompt. If you want to check out other options for Git clients, the Git website has a pretty extensive list.
Create a GitHub Account
It’s free to create a GitHub account and create public repositories. You can learn more and sign up here.
Configure Your SSH Key
Once you have a GitHub account, you will need to configure an SSH key. This allows GitHub to authenticate you without providing your username and password every time. If you don’t already have an SSH key created, you can follow GitHub’s guide to generating a new key. Once you have your SSH key, you can add it to your GitHub account.
If you are using a Git client, you may also need to configure it to use your SSH key. For GitKraken, you select File > Preferences from the main menu. Then select Authentication and set the paths for your public and private keys. If you prefer, you can even have GitKraken create and configure an SSH key for you. Just make sure that the same key is added to your GitHub account.
Create Your Local Repository
The first step in publishing any content to GitHub is to create a local repository (repo) to track your work. This folder will contain all of the files you want to publish to GitHub.
- To create a new repository in GitKraken, select File > Init Repo from the main menu. There will be several options for different types of repositories, but for this tutorial we’ll keep the default Local Only selection.
- Next, choose a folder to be your new repository. You can pick an empty folder, or one that already has files in it; you won’t lose your changes.
- The dialog also includes settings for default .gitignore templates and license files. We’ll skip these options for this tutorial.
- Click Create Repository.
- Open a command prompt window.
- Navigate to the folder you want to use as your repository. You can pick an empty folder, or one that already has files in it; you won’t lose your changes.
- Use the git init command to set up the new repository.
C:\MyGit\Mine\HelloWorld> git init
Add Your Project Files
Now that we have a repository, we want to add our project files. When adding files to an Aras Community project repo, we recommend the following folder structure:
- CodeTree: any files that need to be added/modified in the code tree
- Documentation: any files or documents explaining the project
- Import: any import packages for the Aras database
- Screenshots: any screenshots, videos, or gifs of the project
If your project doesn’t need a particular folder, you can leave it out. You can also include other folders if your project has files that don’t fall into the categories described above. We just try to use the same general structure for our projects so it’s easier to identify files.
In addition to your project’s code, your repository should also include two markdown files:
The README.md file contains the content displayed on your project’s GitHub landing page. It should include basic details about your project, like a brief description, which versions of Innovator your project supports, how to install your project, and basic steps to use your project. If you need a good starting point for your README.md file, Aras Labs has provided a template you can use.
Tip: Visual Studio Code has a great side-by-side preview feature for markdown files.
The LICENSE.md file tells the community how they are allowed to use your project. There are several different licensing models for open source projects. Aras Labs uses the MIT license for all of our community projects. You can read more about the license options using GitHub’s handy tool, https://choosealicense.com/.
Commit Your Local Changes
So far we have created a new Git repository and added our project files to the folder, but it isn’t actually tracking any files yet. We need to commit our files to the repo. There are two basic steps when committing changes in Git:
- “Stage” the changes – that is, select a set of changes that you want to include in a single commit.
- Commit the changes
If we look at our repository in GitKraken, we will see a pane on the right side of the window with three sections: Unstaged Files, Staged Files, and Commit Message. The Staged Files section contains a list of changes that will be included in the next commit. The Unstaged Files section contains all other changes.
Stage the Changes
Right click each file or folder in the Unstaged Files section that you want to commit, then select Stage. If you want to include all changes in your commit, click the Stage all changes button.
Commit the Changes
In the Commit Message section, add a short summary to describe the purpose of your commit, like “Fix typo in readme description” or “Initial import package commit”. If you want to describe your commit in more detail, use the description field, too. Commit messages are important because they help others understand the purpose for the changes in the commit.
Once you are satisfied with the staged changes and your commit message, click the Commit changes button. The new commit will appear at the top of the commit graph, or commit history displayed in the GitKraken center pane.
Stage the Changes
The command prompt window doesn’t automatically display which changes are staged/unstaged, so we need to use the git status command to check. Any staged changes will be listed under “Changes to be committed” and unstaged changes will be listed under “untracked files”.
C:\MyGit\Mine\HelloWorld> git status
To stage changes in a specific file, we use the git add command.
C:\MyGit\Mine\HelloWorld> git add MyFile.txt
To stage all changes, we can use git add with the –all flag.
C:\MyGit\Mine\HelloWorld> git add --all
Commit the Changes
Once our changes are staged, we use the git commit command and include our commit message.
C:\MyGit\Mine\HelloWorld> git commit -m "My commit message here"
Create Your GitHub Repository
- On your GitHub homepage, click the + icon in the navigation bar and select New Repository.
- In the Repository Name field, enter a short, descriptive name. For our projects, we like to use all lowercase characters and dashes (“-“) to replace spaces.
- Enter a brief description in the Description field. This is optional, but it helps users understand the purpose of your project when it appears in search results or in your repository list.
- Keep the default Public setting for your project’s visibility. If you select Private, the community won’t be able to access your project repository.
- Leave Initialize this repository with a README unchecked if you have already created a README.md file for your project.
- Click the Create Repository button to create the new GitHub repo.
Push Your Local Repo to GitHub
Now that we have a new repository on GitHub, we can configure a remote for our local repository and push our project. A “remote” or “remote repository” is a link configured between your local repository and another repository, usually on a server somewhere. This link tells Git where you want to push your local changes to and pull updates from.
- On your repo’s GitHub page, copy the HTTPS url from the Quick Setup section.
- Open your local repo in GitKraken and hover your cursor over the Remote header in the left pane.
- Click the green + button that appears to open the Add Remote dialog.
- How you configure the new Remote depends on your Authentication settings in GitKraken:
- Add from GitHub.com: If you have connected your GitHub credentials in your Authentication settings, you can click the GitHub.com option in the dialog, select your repo from the GitHub Repo drop-down list, and set the Name as “origin”.
- Add from URL: Click the URL option in the dialog, set the Name as “origin”, and paste the HTTPS url you copied into the Pull URL and Push URL fields.
- Click the Add Remote button to configure the remote for your local repository.
- In the GitKraken toolbar, click the Push button.
- When prompted which branch you want to push to in your remote repo, click the Ok button to accept the default setting: origin/master.
- Once GitKraken notifies you that the push succeeded, you can verify by opening the GitHub repo in your browser and refreshing the page. You should see the file contents listed above your README content.
- On your repo’s GitHub page, copy the first command from the section titled “…or push an existing repository from the command line”.
- Paste the git remote command into your command prompt window. (The current directory should be your local repo.)
C:\MyGit\Mine\HelloWorld> git remote add origin https://github.com/EliJDonahue/hello-world.git
- In your command prompt window, run the git push command:
C:\MyGit\Mine\HelloWorld> git push -u origin master
2. Once the command response shows that the push is complete, you can verify by opening the GitHub repo in your browser and refreshing the page. You should see the file contents listed above your README content.
Submit Your Project
Lastly, don’t forget to submit your project via the Aras Community Project submission form! Once your project is reviewed and approved, it will be listed on the Aras Community Projects page for other Aras Community members to find and try out.