Starting guide

Before starting the “Computer Tools for Linguistic Research” course, each student needs to take a few steps that will prepare the necessary tools for further work.

Check you have everything you need

We assume that after completing the “Programming for Linguists” course, you have:

• Python interpreter

• Git version control system

• Development environment Visual Studio Code

• GitHub account

If you do not have any of these, go back to steps 1-5 from Подготовка к прохождению курса.

Fork the repository

To fork a repository on the Github, follow these steps:

1. Open the repository site that your lecturer has sent you.

2. In the upper right corner click Fork.

   

3. Click Create Fork.

   

You have forked a repository! Pay attention to the link in the address bar of the browser: it should contain your Github username and the name of the repository: https://github.com/<your-username>/202X-2-level-ctlr.

Add collaborators

Only you can make changes to your fork. However, during the course, your mentors will need to make changes to your fork: add changes from the main fork, resolve conflicts, etc. You should add them to collaborators, so they have such an opportunity.

To do this, follow these steps:

1. Open the fork site you created in the Fork the repository step.

   1. NB: Pay attention to the link in the address bar of the browser: it should contain your Github username and the name of the repository.

2. Click Settings.

3. Select Collaborators from the left menu.

   

4. Click Add people.

   

5. Enter your mentor’s GitHub username, select it from the list, and click Add <github-username> to this repository.

   

You have sent your mentor a request to be added to the collaborators! Write to them so they can accept your request.

Clone a fork of the repository to work locally

To clone a fork to work locally, follow these steps:

1. Open your fork’s website.

2. Click Code, select HTTPS and click the copy button.

   

3. Open a terminal and navigate to a convenient folder.

   1. To move from folder to folder in the terminal, use the command cd <folder-name>

   2. If you do not know how to open a terminal, go to the Open a terminal step.

4. Run git clone <link-to-your-fork> to clone the repository. For example, git clone https://github.com/vitazaytseva/2022-2-level-ctlr.git.

   1. NB: If asked for a password, enter your Personal Access Token.

Create a project in Visual Studio Code development environment

To create a project in the Visual Code development environment to work with your fork, follow these steps:

1. Open Visual Studio Code and press Open:

   

2. In the opened tab choose the fork folder:

   

Note

You can see in the screenshot that the fork was cloned to folder Desktop (Рабочий стол).

Important

You must choose the fork folder, which has the name format 202X-2-level-ctlr, not the folder with a laboratory work, like lab_5_scraper.

3. In the pop-up window click Yes, I trust the authors:

   

4. Your project has been created. On the left you can see the project files:

   

5. Using the settings icon at the bottom left corner or keyboard shortcut Ctrl + Shift + P open the command palette:

   

6. To create virtual environment, type in Python: Create Environment, then choose Venv option:

   

7. Enter the path to the interpreter you will be using.

8. To activate your virtual environment open the Visual Studio Code terminal by clicking Terminal -> New Terminal at the top bar of the IDE or with a keyboard shortcut Ctrl + `.

   Run the following code:

   python -m venv venv
   

You have created a project!

Note

To run Python scripts you must install Python extension. Open the Extensions tab on the left tab bar (Ctrl+Shift+X). Type in the extension ID: ms-python.python. Install it.

Attention

Visual Studio Code does not save changes in files automatically, but there is auto-saving available. To enable it, click File -> Auto Save at the top left corner of the IDE. Now that you have enabled it, it is not active yet. To control its behaviour, you must set up auto-saving mode in the settings. Use the keyboard shortcut Ctrl + , or use the settings icon -> Settings in the bottom left corner. Then, type in Auto save in the search box field and choose the mode you would like to use. You can find more information about auto save modes in the official Visual Studio Code documentation

Modify source code and push changes to remote fork

You will work on different files in each lab folder. The process looks like this:

1. You change the source code in the file.

2. You commit changes using the git version control system.

3. You push changes to a remote fork.

Change the source code

By default, functions do not have implementations - only pass in the function body. Your task is to implement functions according to the provided lab description.

Commit changes

Git is a version control system that allows developers to save and track changes to project files at once.

To commit the changes, follow these steps:

1. Open the Visual Studio Code terminal by clicking Terminal -> New Terminal at the top bar or with the keyboard shortcut Ctrl + `:

   

2. Run git add <laboratory-work-path>/<laboratory-work-name>.py.

   In CTLR course you are implementing scraper.py and pipeline.py as the laboratory works, and main.py as the final project.

   

3. Run git commit -m "message":

   

Note

As a commit message it is recommended to use short description of the changes you have made. The message will be displayed publically in your fork and Pull Request!

For more information about git commands refer to the official Git documentation.

Push changes to remote fork

After the previous step the changes are in a committed state. They are stored only in your system. To send them to a remote fork, follow these steps:

1. Open the Visual Studio Code terminal by clicking Terminal -> New Terminal at the top bar or with the keyboard shortcut Ctrl + `:

   

2. Run git pull.

3. Run git push:

   

4. Open the main page of your remote fork.

   NB: You will see the commit and the message you wrote.

   

More information about the commands described above can be found in the official Git documentation.

Create a Pull Request

You need to create a Pull Request on GitHub, so mentors can review your changes and validate. To do this, follow these steps:

1. Open the repository site that your lecturer sent you.

2. Select Pull Requests.

   

3. Click New pull request.

   

4. Click compare across forks.

   

5. Click head repository and select your fork from the list (it contains your GitHub username).

   

6. Click Create pull request.

   

7. Enter a name for the Pull Request.

   1. NB: The Pull Request name for Lab 5 must match the pattern: Scraper, Name Surname - 2XFPLX.

   2. NB: The Pull Request name for Lab 6 must match the pattern: Pipeline, Name Surname - 2XFPLX.

   2. NB: The Pull Request name for Final Project must match the pattern: [PROJECT] Final Project, Team N Surname - 2XFPLX.

      

8. Click Assignees and select your mentor from the list.

   1. NB: You can find your mentor in the progress sheet.

      

9. Click Create pull request.

   1. NB: Your Pull Request will appear in the Pull Requests.

Continue working

Your work consists in repeating the following steps:

1. You change the source code.

2. You commit the changes.

3. You push changes to a remote fork.

   1. They will automatically be updated in the Pull Request you created.

4. The mentor reviews your code and leaves comments.

5. You correct the source code according to the comments.

6. See step #2.

Open a terminal

• Instruction for Windows

• Instruction for macOS