Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: updates after summer 2020
Tip

A+ training / workshop will be organized for summer interns 2020based on needs!

Questions?

Send an email to aplusguru@cs.aalto.fi → we can also support you via short online meetings!

Table of Contents

Equipment

  • If For interns: if you need a laptop, screen, mouse, keyboard, something else (you can of course use your own computer, as well!)
    You should have received an email message from HR sent on 20th May - please follow the instructions in the message!
    • Pick up the equipment from CS IT according to the instructions and fill the Doodle beforehand (and if none of the times work for you, contact (after contacting guru@cs.aalto.fi)To enter the campus buildings, access@aalto.fi needs to be informed at the latest on the previous working day by 16.00
  • what your laptop should include:
    • Ubuntu Linux
    • CS IT should have installed Docker and added the user to the docker group. In addition, read the "installing Docker Compose" section below on this page.
    • The preinstalled editors are Eclipse and Vim. You can can install other editors with instructions behind the next link to scicomp (section "Ubuntu packages").
    • More instructions for using Aalto Linux and how to install software: https://scicomp.aalto.fi/aalto/linux/
    • https://scicomp.aalto.fi/training/linux-shell-tutorial/
    • Aalto VPN
    • Zoom and Teams for online meetings
  • If you are not using the laptop provided by us, then macOS is easy alternative. With Windows, a Linux virtual machines is the best choice.

Technical guides

Best practices

Editors

Links to git repositories

Our work is scattered under the apluslms and Aalto-LeTech organisations in github.com. The Acos server has its own organisation too.

...

Installing Docker Compose

Docker Compose ("docker-compose") is another tool besides Docker ("docker"). CS IT should have installed Docker into Aalto work laptops for you (i.e. there should be a package "docker-ce" and a command "docker"). Unfortunately, Ubuntu repositories have outdated versions of docker-compose, so it should be installed manually. It can be installed into the user's home directory without administration privileges. Docker-compose is just a single binary executable file.

...

Show exit codes in the terminal (OPTIONAL)

This configuration is not required for your environment to work for A+ development, but it might still be useful.

...

NOTE: this only works for zsh, thus bash users require something different (e.g. macOS users).

Use nano (i.e. not vim) for git commits with nice colors (OPTIONAL)

In this part, we configure our terminal text editor to nano. which might be easier to use than the typical default vim. In addition, we add custom syntax coloring to git operations.

...

Now, your ~/.profile should look something like the example file in the seciton Installing Docker Compose. You need to log out and in for above changes to take effect.

...

Now, when you issue a command, which uses editor (e.g. git commit), you should see nano with some nice colors.

Creating Python virtual environments

Python virtual environments allow you to install Python packages (libraries and tools) without interfering with the system-wide Python installation. Each virtual environment is isolated from each other, so you can, for example, install different versions of the same package in different environments. You typically create a new venv for each app that requires a lot of dependencies, for example, a venv for a-plus and a venv for the mooc-grader, assuming you develop both systems. We recommend that the venv directory is created outside the application directory, e.g., outside the a-plus source code directory.

...

The source command is used to activate the venv again at another time (in a new terminal window or after rebooting the machine): source venv_aplus/bin/activate

A+ local development setup
Anchor
dockercomposeyml
dockercomposeyml

Course developers usually do not modify A+ source code and they do not need to clone the a-plus git repo. They can run the latest released versions of the A+ Docker containers in order to test their courses. The container version is set in docker-compose.yml.

...

Code Block
languagepy
firstline1
titleaplus/local_settings.py
linenumberstrue
collapsetrue
DEBUG = True
BASE_URL = 'http://localhost:8000/'

Git tutorials and guides

...

Expand
titleElla's quick notes on doing stuff with git
Info

NOTE:

This is NOT a tutorial. If you are unfamiliar with git or unsure of what you are doing, read some tutorials and/or ask for help. If you are not sure what a command does, read the documentation.

Reading documentation in the terminal:
General: man git
Command specific: git <command> --help OR man git-<command> OR man git <command>

Expand
titleUpdating your local repository [and fork] to be up to date with a remote repository

COMMANDS                                                           EXAMPLE (where 'origin' is the upstream and 'fork' my remote repository)
--------                                                           ------------------------------------------------------------------------
git fetch <remote>                                                 git fetch origin
git checkout <branch to be updated>                                git checkout master
git merge --ff-only <remote>/<branch> <branch to be updated>       git merge --ff-only origin/master master
# OPTIONAL: if you wish to update your fork as well
git push <your remote fork> <branch>                               git push fork master

Expand
titleCreating a branch, making commits and pushing them to a remote fork

# start with updating your local repo if it's not up to date

git checkout <branch or commit where you wish to begin your new branch>
git checkout -b <name of new branch>

# make wanted changes

git status
git add <file> # do this for all wanted files, if want just part of a file, use -p
# if you want to add all tracked files, use -u

git commit
# write commit message

# Make new changes and commits as needed

git push <your remote> <branch>

If ready for a pull request, you can create it in GitHub

Expand
titleRebasing a branch

# start with cleaning the branch history if applicable (no PR yet, but there are fixups or things to squash)

git checkout <branch>
git rebase <branch to rebase onto>    # Example: git rebase master

Expand
titleAdding a new commit to a PR

git checkout <branch>
# make the desired changes
git add <file>        # for all the changed files

If an entirely new commit:
git commit
# write commit message

If a fixup:
git commit --fixup=<commit>

git push <your remote> <branch>

Expand
titleCleaning git history

git checkout <branch to clean up>
git rebase -i <commit or tag or branch that is before the things you want to clean>
# if you have fixup-commits, you can also use:
# git rebase -i --autosquash <commit>

# reorder commits to wished order, mark commits that should be squashed to the previous ones with f or s appropriately, etc.
# In Nano, CTRL+K (cuts the line you are currently on) and CTRL+U (pastes the line) may be very useful for reordering the commits

# if the pull request is done and approved, then we can force push the cleaned branch
git push -f <your remote fork> <branch>

Expand
titleAccidentally pressed CTRL+<some key> and things stopped working?
  • CTRL+Z pauses whatever you had in progress
    • You can see what all you have on pause with the command jobs
    • If you have just one job on pause, you can return to it with the command fg
    • If you have several jobs on pause, you can return to the job you wish with the command fg %2, where the number is the number of the job
  • CTRL+S stops the connection between the keyboard and the terminal, all keypresses are stored in a buffer
    • CTRL+Q resumes the connection (and executes everything in the buffer)
    • If you have written something that's in the buffer that you DO NOT want to be executed, you can just close the terminal tab or terminal

Django tutorials (Python web framework)

Testing

Manual testing

Manual testing is always required as well even if you had a lot of automated tests. Mount your source code into the A+ and MOOC-Grader Docker containers and run them in a test course. Think of what can be tested automatically and what should be tested manually.

Unit testing

  • It is easier to run these Django commands in your host machine than in a container. Thus, you need to create a Python virtual environment (instructions are located in this page) and install the requirements (pip packages) from the project (A+ or MOOC-Grader) into the venv.
  • Running unit tests in a Django project: python manage.py test
    • To save time, you can run only a certain test suite with parameters: python manage.py test exercise.tests.ExerciseTest.test_base_exercise_absolute_url
  • New features should be accompanied with adequate unit tests. Create tests for at least the most important cases and also edge cases.
  • Unit tests are made for the backend Django code. We don't have unit tests for frontend JavaScript code (and it is not possible to add any JS unit tests now).
  • We don't have enough automatic tests for our old code base, but at least we should test new features better and always include automatic tests.

Selenium tests

Selenium tests run a browser such as Firefox and execute interactions in the web page according to the test code. They test if the page behaves correctly. Selenium tests are a form of functional testing that tests the system from the end users perspective instead of testing internal functions of the system like unit testing does.

  • A+ has some old Selenium tests. They cover only a small part of the system.
  • Selenium tests are a bit difficult to write and they may easily break when the HTML code of the pages is changed again later.
  • Let's use Selenium tests for only the most important parts of the system, especially when bugs are hard to find manually. For example, end-of-course features, results/points page that teachers use for final grading of the course.
  • A+ has some documentation about its Selenium tests: https://github.com/apluslms/a-plus/tree/master/selenium_test

Git and pull request guidelines

Read these:

  • git commit messages are important and they should explain the reason and background for the changes: https://mislav.net/2014/02/hidden-documentation/
  • Pull Request Etiquette: https://gist.github.com/mikepea/863f63d6e37281e329f8
    • Responsibilities of author (person who creates the pull request) and reviewer (who accepts it)
    • Includes good reasoning why good commit messages are important (in addition to the "hidden documentation" above)
    • Though, doesn't include how to give positive comments
  • About the style of comments and behaviour on pull request https://medium.com/better-programming/pull-request-etiquettes-for-reviewer-and-author-f4e80360f92c
  • There is a pull request template in the A+ repositories. It is used in the pull request description when you make a new pull request. The template reminds you to write clear a description and to discuss how the code has been and should be tested.
  • The pull request title should be written in the imperative form: "Add this feature", NOT "Adds some feature" or "This PR adds a feature".
  • The pull request description is written like normal text. Be clear and concise, but include all relevant information so that readers understand the topic and the need for the changes. Compare writing the description to writing email messages.
  • Naming the git branch for the pull request: the name does not technically affect anything, but it is best to use very short and clear names that describe the topic of the pull request. You will more easily recognize your own git branches later when they have descriptive names. You may include the issue number in the branch name if you like that.

...