Questions and Answers

Git

How do I commit/push my changes?

First you have to stage the files you want to commit.

$ git add [files...]

Or you can stage all files.

$ git add .

You can double-check and see which files you staged.

$ git status

Now after everything is staged, you are ready to commit the changes.

$ git commit -m "Your commit message here"

Now that you have your changes committed, you can push it.

$ git push

Or sometimes you have to specify the remote/branch explicitly.

$ git push origin master

How do I pull the changes?

Simply run:

$ git pull

Or to specify it more explicitly.

$ git pull origin master

I have a conflict, what to do??

If the conflict cannot be automatically merged (non-fast-forward), you can go in the affected files and merge the changes yourself. Your changes and the origin's changes will be marked, you can remove the marking, and merge it manually.

After manually merging the file, you can simply stage your changes, and commit (note that you don't need to provide a commit message).

$ git add .
$ git commit
# [An editor will appear, simply exit it]
$ git push

How do I use 'git X'

Simply run 

$ git help X

Where X is the command you may want to understand. A man page will show up with all the different options, and examples.

I tried to commit, and nano/vim opened. What to do?!

You probably forgot to specify a commit message, simply type your commit message and exit. This also happens when you intentionally leave out the commit message when merging commits, or after an automatic merge. In that case you can exit by :qEnter in Vim, or Ctrl+X with nano. Otherwise;

If it is vim, you'll have to enter INSERT mode before typing by pressing i, then you can type. After you are done, simply press Esc to go back to NORMAL mode, then to save and exit, type :wqEnter.

Otherwise, with nano simply type directly, and press Ctrl+X followed by a Y.

I want to tag my current commit as version X, how do I do that?

Let's say you want to tag the current commit as v0.1, we type

$ git tag v0.1

To push (or pull) the tag, you have to include --tags with your push command

$ git push --tags

And the tag will appear on GitLab.

To delete a tag, simply do

$ git tag -d v0.1

How do I do branching?

Check out the documentation on Git Branching Basics, which provides explanations with diagrams.

Where are good resources on Git?

Check out git-scm docs, which goes in-depth in many aspects of the git tool.

Also check out Oh Shit, Git!?!, you'll need it when you screw up your repo :).

I did something, and I want to force push a commit, but it isn't allowing me. What to do?

GitLab doesn't allow force pushes by default (unlike GitHub), this prevents people from accidentally pushing a corrupted or old repository accidentally to origin.

You will probably have to clone a fresh repository, and salvage the changes from the previous repository manually. This prevents us from corrupting the origin repository.

Documentation

Where can I learn more about LaTeX?

Wikibooks has one of the best documentations on LaTeX. Another nice site is the LaTeX page on Learn X in Y Minutes, which walks you through a document source.

What other things should I learn?

Diagrams are made with PlantUML, which is written in a very minimal format. You can check out examples on their main website.

How do I convert a .tex file into a .pdf?

You need LaTeX installed on your computer, then you can run the command

$ pdflatex file.tex

where file is the name of the file. It will produce a .pdf file with the same name.

What are those .aux and .toc files?

Those files are automatically generated by LaTeX, you should ignore them.

How do I create a .png file from a PlantUML document?

You need to install PlantUML on your system, then simply run

$ plantuml diagram.txt -o diagram.png

Where diagram.png would be your output image file.

Golang

How do I build a binary file?

Make sure you are in the root directory of the Go project, and run

$ go build

Or to directly run the project

$ go run main.go

How do I format the files?

Simply run

$ go fmt ./...

Note the three dots, this recursively formats files in the project tree.

To find issues, run the vet

$ go vet ./...

How to run the unit tests?

To run all unit tests, simply run

$ go test ./...

I want to use a new library, how can I import it?

You can just add it in the package imports section on the top of the Go file you want to use it in. With Go Modules enabled, this should be automatically downloaded when you try to use go run or go build.

Otherwise, you can run

$ go get ./...

Where can I learn more about Golang?

Going through the Golang Tour is a great way to learn the language, you could also try to solve some problems on Project Euler, which would also strengthen your programming skills in general.

Learn X in Y Minutes have their dedicated page on Golang too!

How is the directory structure organised.

Check out the Go project structure in the Main Style Guide.

Where are the documentations for the libraries used?

XORM

XORM is the Object-Relational Mapping library we are using, this automatically hooks up with any database engine (PostgreSQL/SQLite/MySQL, or even MSSQL.. ew). This engine automatically generates the schema, and syncs the database. It also does the heavy-lifting for CRUD queries. You can check the documentation on their website.

Macaron

Macaron (or Go-Macaron) is a minimal web framework for Go, do note that this library relies on Go's built-in net/http library on many things, such as templating, and the framework is just a middleware between you and the net/http library. So it is important to know what is provided by the built-in library or Macaron, so you can find the appropriate documentation.

Usually if it relates to these points, it is a Macaron thing:

  • Routing (and parameters in URLs)
  • Templating (built on top of Golang's templating, so it is mostly identical)
  • Data binding (forms bound to structs)
  • Sessions and cache
  • Captchas and CSRF protection

Check out Macaron's wiki as it contains really helpful information, and it will be used very frequently as a reference, just like XORM's docs.

Urfave's CLI library

To keep the command-line usage of the program neat and simple, we use urfave's cli library. This allows us to have multiple command-line commands, with flags and options, in a neat way. This is very simple, and usually just setup a couple of times when adding new commands in the beginning of the project's life-cycle.

BurntSushi's TOML

We use BurntSushi's TOML library for handling TOML files. We use the TOML as the configuration file format, you can check out TOML's language spec. It is supposed to be better than YAML and INI (also, ew) format.

Testify

To help with writing unit tests, we use the testify unit testing library which simplifies the testing. Although Go provides a testing library, it does not have assertions. This library provides them, among other things, such as data mocking with its mock package, among other things.

Other libraries

If there are other libraries, you can check them. A good tool is the go doc command-line tool, also a better tool is the GoDoc website, you can simply enter any package and it will download it, and preview a web documentation.

It is important to also be aware of Go's built-in library, as it is really powerful.

A nice website for discovering libraries is Go Awesome, it is also a source of inspiration.

Learning by example

A project called Gitea is one of the main inspirations of this projects layout, and it uses the same libraries listed above. You can learn by checking out Gitea's source code, as it is done and structured similarly to our project.

General programming

How do I run Makefiles?

To run Makefiles you need GNU Make installed on your system. Then you are able to use the make command, which will run the Makefile in the current directory.

Makefiles may have multiple rules, such as clean, build, or all to run all rules (and produce a target). Consult the README file of the project, which would list the appropriate make commands for different scenarios.
Usually, you would run a command like

$ make all

Usually, Makefiles are simple and don't require modification once things are set.

What editor/IDE should I use?

Use whatever you like.

If you are here for some recommendations, then:

  • Visual Studio Code (currently trendy, but has poor speed performance)
  • [neo]vim and emacs (has a learning curve, but pays off in the long run)
  • Jetbrain's GoLand (made by same company who made IntelliJ)
  • Geany (a good lightweight alternative to VS Code and other Electron-based editors)

Do I need to use Linux?

Using Linux (or most Unix-based/like systems, this includes macOS) will help with development, as the tools can be run locally. Unlike with Windows, you may need to work-around with Windows Subsystem for Linux (WSL) or Cygwin, which might not work as expected like on a proper Unix system. Although it is not necessary, especially with organisational roles.

How to get Linux?

Ubuntu is a popular Linux distribution, which is easy to install and has a lot of online support.

Which programs should I have installed on my system?

You should have these packages installed on your system:

  • git: For version control.
  • LaTeX: For document typesetting.
  • GNU Make: For build automation.
  • Go: The programming language.
  • PlantUML: For diagram generation.

Other programs worth installing:

  • A database server, such as PostgreSQL or MariaDB
  • zathura: A minimal PDF viewer which reloads files automatically when updated.
  • sxiv: A minimal image viewer which reloads images automatically when updated.

How do I get a fancy badge?

You can get one at https://shields.io/, and add it in Settings>General>Badges on GitLab project or group.

Do note that our repositories are private, so shields will not be able to view the statistics of our projects.

My CI build failed, how do I undo it?

There is no need to undo anything. Simply figure out why the CI build failed, it could be due to formatting or compilation issue. Make sure you run make to format and test the project before committing and pushing to GitLab.

But it happens sometimes, and it is fine. This is the reason why we have CI.