A+ training / workshop will be organized for summer interns 2020based on needs!
Send an email to firstname.lastname@example.org → we can also support you via short online meetings!
|Table of Contents|
- 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!
- 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/
- 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.
- Coding style guide: we don't have guide of our own, but in Python, the official PEP 8 is good: https://www.python.org/dev/peps/pep-0008/
- Contribution guide, (link to be added here!)
- Git and pull request guides are on this wiki page
- Definition of Done
- Eclipse (available by default)
try this https://snapcraft.io/atom and report to Jaakko on succes/failure
- Visual Studio Code (vscode),
try this https://snapcraft.io/code and report to Jaakko on success/failure
- Download .deb package: https://go.microsoft.com/fwlink/?LinkID=760868
sudo apt install ./<file>.debin the Downloads folder (or where the file is)
- others? inform preferably CS IT in advance
- Instructions on how to change the terminal to another
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.
- The official Docker Compose installation guide: https://docs.docker.com/compose/install/#install-compose.
- About .zprofile and .profile with zsh (the default shell in Aalto linuxes): https://superuser.com/q/187639
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.
~/.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
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.
DEBUG = True BASE_URL = 'http://localhost:8000/'
Git tutorials and guides
- Linux Shell tutorial from the CS IT: https://scicomp.aalto.fi/training/linux-shell-tutorial/
- We recommend that everyone knows how to use git in the command-line. GUI's support most basic features, but some more complex operations are typically missing.
- Basics in the first two chapters of the Pro Git book: https://git-scm.com/book/en/v2
- Set your name and email to git: https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration
- You might want to change the default text editor for writing commit messages. Nano is a simple editor if you are not very familiar with the command line:
git config --global core.editor "nano" (or see Use nano for git commits above).
- Reminder of git commands (and some workflows to manage changes):
- You must understand the following commands before you can do anything: git status, git log, git add, git commit, git pull, git push, git diff (--cached)
- Branches and merging (entire chapter 3): https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell
- Branches are crucially important for separating your work from the upstream master version while you are working on your feature in a topic branch. You must understand the commands: git fetch, git checkout, git branch, git merge
git lolfor visualizing the branches:
git config --global --add alias.lol "log --graph --decorate --pretty=oneline --abbrev-commit --all" (source)
- Rebasing: https://git-scm.com/book/en/v2/Git-Branching-Rebasing
- Rewriting history (squash, change commit messages, reorder commits, interactive rebase): https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History
- git reset can be used to:
- remove staged changes (reverse of git add)
- remove changes in working tree (git reset --hard), though use
git checkout filename, so you don't make mistakes
- "delete" your local commits from a branch when the local branch has a different history than the remote and you want to use the remote version (i.e. change where the branch points to)
- Git submodules (course repositories add the a-plus-rst-tools repo as a submodule): https://git-scm.com/book/en/v2/Git-Tools-Submodules
- Stashing, i.e., saving work and removing it from the work directory without committing: https://git-scm.com/book/en/v2/Git-Tools-Stashing-and-Cleaning
- GitHub.com pull requests: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests
- Git tutorial from the DigitalOcean community: https://www.digitalocean.com/community/tutorials/how-to-contribute-to-open-source-getting-started-with-git
- Git does not remove commits, so if you lose changes, but did commit them at some point, you have ~30 days to get them back. Contact a git guru!
- Finally, check pull-request guides below.
Django tutorials (Python web framework)
- Django is the Python web framework used in A+ and the MOOC-Grader. A web framework contains interfaces to functionalities that are often needed in the web (backend) development, such as HTTP requests and responses, databases (object-relational mapper) and rendering (HTML) templates.
- Web software development course at Aalto: https://mycourses.aalto.fi/course/view.php?id=24331 and https://plus.cs.aalto.fi/wsd/2019-2020/
- Basic tutorial: https://docs.djangoproject.com/en/2.2/intro/
- Topics that most people should probably understand:
- database, models, making queries
- HTTP requests, view classes, generic view classes
- user authentication
- Forms, form validation
- (HTML) templates, Django template language
- Migrations, how to generate migrations after you change the fields in model classes
- unit testing
- security (HTML escaping in templates, XSS, CSRF, SQL injection, access control): https://docs.djangoproject.com/en/2.2/topics/security/
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.
- 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.
- 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 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
- 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.