Skip to content

Latest commit

 

History

History
80 lines (48 loc) · 5.52 KB

how-to-use.md

File metadata and controls

80 lines (48 loc) · 5.52 KB
Raw

How to use the skeleton repo and the README template

Table of contents

How to use

For a new project, create a new repo here on github.com under the KTH-SSAS organization.

Screenshot_20200928_183729

Give a name to the new repository, preferebly prefixing the name with the parent project's name. Also, choose to make your repo public or private depending on its contents:

Screenshot_20200928_184442

Press Create repository.

Once created, this skeleton repository needs to be copied to the new one.

The simplest way is to click on Import code and use the skeleton's repo url (https://github.com/KTH-SSAS/skeleton/) (you may need to resumbit your github.com username/password):

Screenshot_20200928_184856

Click Begin import. Your repository will then have the same structure as this one and you can start editing it to update this README, add folders/files, etc.

Alternatively, if you are comfortable with git, you can clone this repo locally, change the remote to your project's github url, makes local changes and, then, push them to the project's github repo. This way you can also rewrite the repo's history to remove any commits that originate from this skeleton repo.

Important repository settings on Github

Make sure to add a repo description on Github as well as relevant tags to boost discoverability and exposure:

Screenshot_20200928_191955-1

Also, from the repository settings, you may want to disallow forks.

How to update the README

Remove the placeholder content and these instructions and add your content that suits your project. This README has comments in various places to explain what some lines of code do and how you can modify them.

What files do I upload to github.com?

Git is designed primarily for text based files. These can be tex files, code, svg images, etc. Git also manages small binary files quite well, for instance, small images. However, large files such as applications or huge images are better managed by another appllication. When you need to host such files, use the KTH box or dropbox service to upload them there and place a link in the Project Links section of this README.

Also, do not add PDF files generated from the tex files included in your repo. The PDF file should be able to be generated by compiling the tex code and you can also add a link to the Overlead project that will also show a compiled pdf.

Image use

This template has an image in the header. You can keep the same image or use a project specific one. Or you can choose to not use one. The image is used to make the README nicer but also to differentiate the KTH-SSAS repos that use this README template with each other. Try to use an image that is relevant to your project (see this example

Project Management

A big reason behind using Github for KTH-SSAS is its integrated project management features. There is an issue tracker, a kanban board and support for milestones. You can find your way through those and use them as you see fit. Some advice:

  • break down pending work for your project into digestable steps and create separate issues for each one of them,
  • use labels for you issues to better organize them
  • create milestones with dates to track work before a deadline (e.g. before a conference talk or a journal submission)
  • use the kanban boards (Projects) for keeping better track of your project's progression.

Overleaf integration

Overleaf is an online tex editor. KTH offers the paid plan to KTH students and employees. You can write your tex code directly on Overleaf. But not everyone uses Overleaf. To make the tex code more broadly available and allow others to comment, push fixes, etc, host the tex code on your project's github page and setup Overleaf to read it from there.

To do so, you need to visit your Overleaf account's settings and setup Github Integration from there. Once setup, you can:

  • (recommended) create a new Overleaf project from an existing github repository (i.e. your project's repo that you have created based on this skeleton), or
  • (not recommended) import an existing Overleaf project into github (Overleaf will create a new github repository and you will need to copy files from this skeleton repo manually to the new repo created by Overleaf).

Once everything is setup, you can keep on working on Overleaf on your tex documents, but you need to remember to push periodically new changes back to github. This can be done by opening a project in Overleaf, clicking on the upper left sandwich menu and click Github under Sync.

Example

A github repo that already uses this template is located here.