In summer 2020, we work remotely because of the Force Majeure situation, and remote work concerns also summer interns for the whole summer!
Tools for remote work
Equipment: laptop and screen
- to be picked up from CS IT, and agreed on in advance (firstname.lastname@example.org and email@example.com)
- You should have received an email message from IT, sent on 20th May - please follow the instructions in the message!
- To enter the campus buildings, firstname.lastname@example.org needs to be informed at the latest on the previous working day by 16.00
- what the laptop should include:
- CS IT should install Docker and add the user to the docker group. Just remember that user group changes become active only after logging out and in again in the laptop. CS IT could install docker-compose too, but it must be installed manually by downloading the binary since Ubuntu package repositories have too outdated versions of it. Instructions below.
- an editor: eclipse by default; if you need some other (e.g. atom), it would be good to inform about it
Tools for planning and communication at remote work
To keep in contact with your team while working remotely, you need online communication tools. These are an essential part of our work during the summer, so please pay attention to these:
- Online meetings with Zoom and Teams
- Most likely you need these both.
- Instructions for Teams: https://www.aalto.fi/en/services/microsoft-teams-quick-guide and for Zoom: https://www.aalto.fi/en/services/zoom-quick-guide
- Log in with your Aalto user account. NOTE that to be able to log in Teams, you need to install the Microsoft Authenticator app on your mobile phone for Multifactor authentication - so book some time for logging in for the first time!
- You can install Zoom and Teams on your mobile phone, as well. Both are handy for meetings and interaction during the working days
- Planning your work with Aalto calendar
- To plan your daily and weekly work, and to agree on meetings with colleagues, you need the Aalto calendar. It is at least available in Teams and via mail.aalto.fi.
- To send calendar invitations with a Teams meeting, in Linux you need to use the calendar via Teams.
- Remember to reply (i.e. accept/reject) the calendar invitations you receive with a response - otherwise the invitation sender cannot know, whether you have received the invitation and whether you are participating or not.
- It could be good to specify whether the invitations can be replied to in both Aalto-email and Teams.
- Should there be instructions somewhere for how to join a meeting on Teams? (By pressing "Join" on the box of the meeting in the calendar. Can one join a meeting before it has officially begun?)
- Online communication channel available for the whole team for the whole day: The team EDIT (you will be added there)
- channels for weekly stand-ups, daily meetings, and for general discussion (and we can e.g. create channels for subprojects, based on needs)
- you can start an instant video meeting on any suitable channel, and you can write in the chat
- remember to edit each channel notifications (from the "..." next to the channel name) to follow the discussion!
- you can call people with Teams (like e.g. Whatsapp) whenever needed. Use the tab Calls in the left hand side menu.
- You can call and reply to calls with your mobile phone or your laptop
- You can share your screen in the Teams meeting/call, to ask for advice
- you can tag individual people or the whole channel/team, traditionally with the @-sign.
Get-together & orientation
- By CS HR: the orientation meeting to all CS summer interns; it includes practical information (link to contents will be updated here after the meeting).
- on Monday, June 1 at 10.00-12.00 in Zoom
- By the EDIT team:
- this page
- first meeting on June 1 at 13.00-15.00 in Teams (link available in the calendar invitation)
- You should have received an email or calendar invitation to the meetings.
- Check before the meeting that the online meeting tool works for you! Contact Anni if you have technical problems.
- team leader: Anni
- clients: teachers who have requested for the features
- instructors: Markku, Jaakko, Jhosimar
- team members: Ella, Henrik, Matthew, Saara, Veera (each with individual responsibilities)
Routines to support our daily work - let's agree times for these:
- for discussing what you have done since the previous daily and what have you planned to do before the next one - here you have a good opportunity to ask questions and agree on instant meetings in smaller groups!
- let's agree on a suitable time - would be nice to meet as soon as the whole team is available, e.g. at 9 or 9.30 or 10.00 (some team members might start their days earlier and some later)
- weekly stand-up:
- overview of week planning
- during spring, we have had chat weekly stand-ups - in the summer, do we want to continue this or use some other method?
- sprints? planning and follow-up?
- work locations: during summer, only remote days (until August at least)
- a tool for discussions and asking for help during the day: a Teams team (including instructions on how-to for asking help)
- 1to1-discussions with Anni e.g. biweekly
- daily working hours
- 7h 21mins per day, in average (for 100% contracts) - aim at working regularly; during office hours, and during week days (not evenings or weekends)
- joint working hours: some hours for the whole team, e.g. 10-15, to support collaboration in the team
- opportunity to use the clock card (tiima, mobile app available) → instructions/best practices for taking to use & using
- EDIT wiki (this wikispace)
- slack: #edit-team
- Teams: created team
- Coding style guide
- Definition of Done
- Version control routines
- Instructions on how to change the terminal to another
Exit process at the end of the summer
- document your work and make sure that it is available for the core team
- return work laptops and other equipment (e.g., laptop docks) to CS IT
- eclipse (available by default)
- atom (how to get it to use)
- others? inform preferably CS IT in advance
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
- At least I find it intuitive to go in order and do things in the order they come up. Is this step done first before fetching the git repositories? If the git repos should e fetched first, it would be good to say it explicitly. Or at whatever spot they should be fetched, it would be good to mention it (and if it's done at any point before "A+ local development setup" and the sections listed above it, it would be good to mention that there are instructions concerning git towards the bottom of the page). There is so much new information, that it would be good to kind of provide a step-by-step guide to help with acclimation.
(Note: docker-compose is another tool besides Docker. CS IT should install Docker (docker-ce) into Aalto work laptops.) 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 sudo privileges (in Linux). Docker-compose is just a single binary executable file. After downloading it, it should be moved to a directory that is in the PATH environment variable so that the command docker-compose works without typing the full absolute file path to the binary. More details below.
Docker documentation has installation instructions for docker-compose: https://docs.docker.com/compose/install/#install-compose. The curl command there can be modified if you don't have sudo privileges. Basically, we download the file to the home directory instead of the path /usr/local/bin.
Check the latest version number of Docker Compose from its GitHub page: https://github.com/docker/compose/releases
mkdir -p "$HOME/.local/bin"
curl -L "https://github.com/docker/compose/releases/download/1.25.4/docker-compose-$(uname -s)-$(uname -m)" -o "$HOME/.local/bin/docker-compose"
chmod +x "$HOME/.local/bin/docker-compose"
Aalto Linux uses Zsh shell by default. Open the .zshrc configuration file:
Add this line there:
The new modified PATH is active when you open a new terminal window.
- When I opened the new terminal, it displays a number in between the "~" and "%" (number grows consequtively). Is it supposed to do that?
Creating Python virtual environments
- Is this done in the home directory or where?
- In what instances are Python virtual environments needed? And who needs them?
- Should this be done immediately or should the repositories from GitHub be fetched first?
aptdcon --install python3-venv
python3 -m venv venv_aplus
pip install --upgrade pip setuptools
pip install wheel
# in the a-plus directory
pip install -r requirements.txt
The source command is used to activate the venv again at another time (in a new terminal window).
- What is the a-plus directory mentioned in the comment above? The a-plus repository fetched from git? If is is, it apparently should be fetched before this is done. It would be good to mention that.
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.
A+ and MOOC-grader developers need to mount the source code to the Docker containers so that they can run their own version of the source code in the container. Example paths for the volumes field in docker-compose.yml:
- The first path before the colon is the local path that you need to fix for your own computer.
aplus/local_settings.py is needed when you run Django manage.py commands (such as makemessages, compilemessage, makemigrations)
DEBUG = True
BASE_URL = 'http://localhost:8000/'
- We recommend that everyone knows how to use git in the command-line
- 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"
- 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
Alias git lol for visualizing the branches: git config --global --add alias.lol "log --graph --decorate --pretty=oneline --abbrev-commit --all"
- 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 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.
- 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
Django tutorials (Python web framework)
- What is Django? → short description here + link to WSD material
- 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/
- 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.
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
- You create new PRs for new features and fixes that logically belong together. So, one PR for one feature. The contents of one PR should constitute a logical set of changes for the whole feature. A pull request does not always add a new feature, since there are also bug fixes and other necessary changes without adding new features.
- You modify the PR by pushing new commits when you fix bugs and other issues that have been pointed out in the code review and testing.
- You should clean up the git history before creating the PR. While the PR is being reviewed, you make changes in new commits and do not squash so that reviewers can easily follow the latest changes (the newest commits). At the end when everything has been polished, you clean up the git history again (git squash etc.) and force-push.
- There can be more than one commit. Each commit should constitute a sensible set of changes that somewhat belong together. The code should usually always "work" after each commit, so don't leave the code in a completely broken state after a commit (syntax errors, immediate crashes when executing the code). Of course, not every detail can work after a single commit when large features are split into many commits, but there are usually logical subcomponents or such.
- Massive commits are hard to read when developers track changes afterwards (for example, while bug hunting). A large number of very small commits is also hard to digest.