Tutorial: Submitting a pull request to Cocos products

How to submit code to Cocos

Like Cocos2d-x, Cocos Creator is also an open source game engine. This includes our code, examples and documentation, are open source.

In the process of developing your game, when you find that the engine, documentation, or examples are not perfect, if you only make suggestions to the official team, the official team may not be able to follow up in time due to limited human resources. We welcome all users to actively submit pull requests (PR) to help Cocos get better and better. Does the engine have a bug? Submit a PR! The sample is ugly? Submit a PR! API comments are not clear? Submit a PR! Is there a typo in a document? Submit a PR! Want to contribute your valuable changes to the gaming community? Submit a PR! Are you beginning to notice a pattern? We welcome submissions to further progress Cocos products.

The following are commonly used open source repositories, which can accept PR’s:

Let’s take a look at how to submit code to Cocos on GitHub from scratch.

Prerequisites

Sign up for a GitHub account

Browse to GitHub to sign up for an account or login with your already existing account.

Review GitHub basics

It is important to review the basics of using GitHub. It would be a lot to cover every topic in a single tutorial. There is also a really good Simple GitHub Tutorial that is a must read.

Understand basic GitHub terminology

There are some basic terms that every developer working with GitHub should know. These definitions are taken directly from GitHub’s documentation.

  • GitHub - GitHub is a code hosting platform for version control and collaboration. It lets you and others work together on projects from anywhere.

  • Repository - A repository is usually used to organize a single project. Repositories can contain folders and files, images, videos, spreadsheets, and data sets – anything your project needs.

  • Branch - Branching is the way to work on different versions of a repository at one time.

  • Commit - On GitHub, saved changes are called commits. Each commit has an associated commit message, which is a description explaining why a particular change was made.

  • Pull Request - Pull Requests are the heart of collaboration on GitHub. When you open a pull request, you’re proposing your changes and requesting that someone review and pull in your contribution and merge them into their branch. Pull requests show diffs, or differences, of the content from both branches. The changes, additions, and subtractions are shown in green and red.

  • Merge - When a pull request is joined in with the code of a branch. Thus making it part of that branch for others to work with.

  • Origin - the location of the repository that contains the code to be worked it.

  • Fork - a personal copy of an origin repo.

Installing Git - command-line

Git needs to be installed on your computer. If it is not already installed you must obtain the Git software and install it. Some resources can be found on git-scm and this gist. Once installed, entering git on the command line should produce the following:

You are now ready to begin using Git. There are other tools you may want to consider, especially if your command-line chops aren’t quite stellar yet.

Installing Git - GitHub Desktop

GitHub Desktop is a GUI application for working with Git Repos and it is made by the folks at GitHub. You can use your existing GitHub credentials. Download it and install it if you wish to use it. It is east to get started, just launch the app and follow the prompts.

Working with Cocos Creator and GitHub

Now that you have reviewed the basics and decided if you will be using the command-line or GitHub Desktop we can work with the Cocos Creator Docs repo. It is important to first view this repo on GitHub.com so you can see what this interface looks like. You will need to use this interface for a few operations (i.e forking a repo, covered later).

Cloning repositories

The first step in most situations is to clone the repository of the project you want to start contributing to. We will use the Cocos Creator Docs repo as our example throughout this process.

Command-line:

# clone the Cocos Creator docs repo to some location on your hard drive
# that makes sense to you.
git clone https://github.com/cocos-creator/creator-docs

# change to the Cocos Creator docs directory, where ever you put it.
cd /Users/s-m/creator-docs

The output looks something like this:

GitHub Desktop:

It is easy to clone with the following screenshots:

When you click Clone, you will see a progress screen:

Once the repo is cloned, you can begin working with it.

Forking repositories

Forking a repo means that you take a copy of an existing repo and it appears under your GitHub account. You fork a repo so that you can make changes to it. These changes are isolated away from the projects repository that you cloned. You can experiment with code changes, help fix typos, anything you wish to help with. You need to use the GitHub Web Interface to fork a repo.

Once forked, you will see a new repository has been created that references the original project:

You can either use the command-line or GitHub Desktop to work with the forked repo.

Command-line:

On the command-line you can simple add a new remote location. This tells GitHub where the origin repository is and where your forked repository are. This allows your fork to pull updates and submit pull requests to the origin repository. Here is an example:

# cd into the directory where you cloned the project
cd /Users/s-m/creator-docs/

# show current remote locations
git remote -v

# add a remote repo replace 'MyForm' and '<your github id> with proper values
git add remote MyFork https://github.com/<your github id>/creator-docs

# now re-run git remote to see this change has occurred
git remote -v

Here are a few screenshots to demonstrate the output of these commands:

GitHub Desktop:

Using GitHub Desktop you still need to fork using the web interface, using the same instructions above. You can always get to the web interface for a repository from GitHub Desktop:

Once you have forked, you can quickly get into GitHub Desktop to start working with your fork:

Back in GitHub Desktop we can see and use the forked version to start making changes to submit back to the origin.

Making changes (by branching first)

Before you start making changes, it is appropriate to cut a new branch to perform your changes in. This gives you a working playground that doesn’t affect the master branch. If your changes don’t go your way you can simply delete the branch and cut a new branch from master again and try again.

Command-line:

# cut a new branch from master to perform changes
git checkout -b MyNewBranch

# checking which branch you are currently on
git branch -v

GitHub Desktop:

Pulling changes from origin

When making changes, it might be necessary to pull any new changes that have been merged during your development time. When you submit a pull request GitHub will tell you if it can be merged successfully. If it cannot, GitHub will require you to pull changes from the origin and fix any merge conflicts. It may be beneficial to pull often to ensure merge conflicts are fixed along the way. To pull:

Command-line:

# pulling from origin
git pull origin master

GitHub Desktop:

Pushing changes to origin via a Pull Request

It is a good idea to commit and push your changes to your remote repository often. This secures them up in the cloud for safe keeping.

Command-line:

# check the status of a repo
git status

# checking which branch you are on
git branch -v

# adding all changed or untracked local files to git
git add .

# adding specific changed or untracked local files to git
git add en/getting-started/history.md

# committing all changed files to GitHub
git commit -m 'I changed these files' .

# committing specific changed files to GitHub
git commit -m 'I changed these files' en/getting-started/history.md

# pushing committed changed up to GitHub
git push -u <remote repo name> <branch name>

GitHub Desktop:

You can commit and push as often as you wish. Once you are satisfied with your work, it is time to create a pull request.

Creating a pull request

Creating a pull request is your way of telling the origin project that you have made changes you want to be considered for merging into their project. When creating a pull request, it doesn’t matter if use the command-line or GitHub Desktop, it is down from within a browser window. In fact, GitHub Desktop will open a browser window automatically for you.

Once in the browser, follow the prompts to create a new pull request. It is always good to verify that your pull request is being merged with the correct origin branch and that the changes you made all seem to be there. If something is missing you may have forgotten to add, commit or push changes to the remote repository.

After creating the pull request, it can be edited, have additional commits and developers can even talk about the work you submitted.

Additional considerations

There are a few things developers may want to consider that are outside the scope of this tutorial.

SSH versus HTTPS

GitHub offers both SSH and HTTPS protocols for working with repositories.

Please review SSH vs HTTPS. It might also be helpful to review using SSH Keys and incorporating them into your workflow.

4 Likes