Skip to content

Forking this Template

Jump to bottom
AB edited this page May 5, 2021 · 1 revision

Contents

  1. Using This Template
  2. Forking

Using this Template

This repository is setup as a template. To read more about how to use a template and what a template repository is, see GitHub's doc page.

Before you begin, note that the main workflow file uses the pull_request_target trigger. This means that pull requests from forks will run workflows in the base branch, and will have access to repository secrets. For the base template repo, this is not a security concern since the only secret used in tests is DJANGO_SECRET_KEY, and is meaningless in this repository. However, an instance of this repository will likely have other secrets set. Unless you are absolutely sure that code run by workflows for pull requests, such as tests, does not have access to important secrets, you should change this trigger type back to pull_request. This means that pull requests from forks (of your fork) will not run actions. Alternatively, if tests only need access to secret keys so they don't complain, use a different secret in the workflow files for running tests.

Forking

If you are interested in receiving updates to this template in your project, we recommend that you fork this repository into your own account or organization. This will give you the entire commit history of the project, and will allow you to make pull requests from this repository into your own to perform updates.

Unfortunately, GitHub does not allow you to fork your own repository. As a result, the forking option is not available to the owner account or organization. This means that IEEE UofT cannot use this template by forking it, and if you choose to fork your own generic copy of this template for instantiating, you will not be able to fork that fork.

Note: develop is our default branch, but it should not be considered the most stable branch. If you want only the most stable releases, we recommend that you apply your customizations on top of the master branch.

From the Template

This is our recommended approach to instantiate this template, if forking is unavailable to you. In the end, this gives a similar result to copying the repository (below), but maintains the "generated from ieeeuoft/hackathon-template" message on GitHub. If you don't care about that, then copying is simpler.

  1. Create an instance of the template by clicking "Use this template". image

    Note: By default, using a template creates a new repository based off only the default branch, which for this repository is develop. We recommend that you apply your customizations on top of the more stable master branch. To do so, make sure you check "Include all branches".

    Creating a repository from a template flattens all commits into a single initial commit. If you never plan on merging updates from the upstream template, you may proceed in customizing your instance from here and ignore all of the following steps.

  2. Clone your new instance locally via the method of your choosing.

  3. In order to pull history and updates, you will need to add the original template as a remote on the git repository. Note that this only happens on your cloned instance, changing remotes has no effect on the repository you created on GitHub.

    $ git remote add upstream git@github.com:ieeeuoft/hackathon-template.git

    If you do not have git configured to clone over SSH, you may use the HTTPS url instead: https://github.com/ieeeuoft/hackathon-template.git

  4. Merge in whichever branch you would like to base your customizations off from upstream right away to get the history. For the rest of this example, we assume you are using master.

    $ git fetch upstream
$ git merge upstream/master master --allow-unrelated-histories
$ git push origin master

  5. Use the repository as you see fit, by creating feature branches off of master. We recommend a Gitflow workflow.

  6. When you want to pull an update from the upstream template, we recommend merging it into a new branch so that you can review the changes, resolve any conflicts, and merge it into your base branch by a pull request for added visibility.

    $ git checkout master
$ git checkout -b update-from-upstream-template    
$ git fetch upstream
$ git merge upstream/master update-from-upstream-template
$ git push -u origin update-from-upstream-template

  7. Make a PR on your repo to merge update-from-upstream-template into your base branch.

Copy the Repository

This approach is very similar to using the template, but you lose the "generated from ..." text. You gain the added benefit of keeping the entire commit history of the repository, and not having to deal with fetching it upfront.

  1. Import a new repository at https://github.com/new/import. Set the old repository's clone URL to https://github.com/ieeeuoft/hackathon-template.git.

  2. Clone your new instance locally via the method of your choosing.

  3. Add the original template as a remote on the git repository.

    $ git remote add upstream git@github.com:ieeeuoft/hackathon-template.git

    If you do not have git configured to clone over SSH, you may use the HTTPS url instead: https://github.com/ieeeuoft/hackathon-template.git

  4. Use the repository as you see fit, by creating feature branches off of master. We recommend a Gitflow workflow.

  5. When you want to pull an update from the upstream template, we recommend merging it into a new branch so that you can review the changes, resolve any conflicts, and merge it into your base branch by a pull request for added visibility.

    $ git checkout master
$ git checkout -b update-from-upstream-template    
$ git fetch upstream
$ git merge upstream/master update-from-upstream-template
$ git push -u origin update-from-upstream-template

  6. Make a PR on your repo to merge update-from-upstream-template into your base branch.

Clone this wiki locally