Note: Please treat these exercises also as
professional work. For example, instead of asdfg use more
meaningful commit messages like Add acceleration feature or
Fix #5 (you can find detailed advice in the How to Write a Git
Commit Message and the Git Style Guide
posts).
Initialization
In most of the exercises we use command line tools instead of IDEs,
since only those can be used in a CI environment. Moreover, you can
learn more this way for beginner exercises.
You will need the following software to complete the lab (these are
available on the virtual machine template in the laboratory, but you can
use your own machine too):
- Java JDK 11 or newer
- Git command line
- Apache Maven 3.6.0 or newer
- A simple IDE like Visual Studio Code
- Extensions: Extension Pack for Java, Sonarlint
Important: If you use your own machine, then check
that Java JDK is configured correctly: use JDK and not JRE, set
PATH
and JAVA_HOME
(see here in
details).
java -version
javac -version
- Fork the https://github.com/ftsrg-retelab/base project to your
GitHub account. If you don't have a GitHub account yet, then please
register one, confirm the e-mail address and then you can fork the
mentioned project.
- Initialize your development environment. You will use
- CLI tools (marked by [CLI]),
- any type of IDE or editor (marked by [IDE]) on your
desktop to edit Java code. You should also have a git client, either
built it into the IDE or a CLI version.
- Browser (marked by [WEB]) on your desktop to use
GitHub web UI and other online CI tools
GitHub access token
Important: Since 2021 you cannot authenticate with
passwords to GitHub from the command line. You should create first a personal
access token (PAT), and use that from the git commands.
Important: Personal access tokens are like
passwords and have the same inherent security risks. Always assign as
few permissions as possible to our token!
- On the GitHub interface, click on your own profile, then select the
Settings menu item.
- At the bottom of the left side bar, select the menu item
<> Developer settings.
- In the left sidebar, select Personal access token and then
Fine-grained tokens.
- Click on the Generate new token button.
- Give the token a name, set its expiration date to the closest time
after the last lab (MIT-4).
- From the accesses (Repository access), select the Only
selected repositories option and select the previously
forked repository under our own user.
- Finally, click the Generate token button.
- The generated token must be used instead of
password during the git push operation.
Markdown exercises
- [CLI] Clone your own project using the Git
client.
- [CLI] Modify the README file in the root of the
project, add new comments using Markdown
syntax. Use at least 3 types of formatting!
- [CLI] Check which files are not currently under
version control (
git status
), add any new or modified files
to the current index (git add
), commit them
(git commit
), then push the new content to the repository
instance on GitHub (git push
).
- When executing the
git commit
command for the first
time, the configuration of the user and email address may be missing,
these can be done with
git config user.email "you@example.com"
and
git config user.name "Your Name"
to do.
GitHub Flow Exercises
- [WEB] Open the project on your
GitHub.
- [WEB] Click Settings.
- [WEB] Enable the Issues option in
the General menu on the left.
- [WEB] Read the project's README to familiarize
yourself with the application you will be working with.
- [WEB] Define a new feature or change request and
create a bug ticket (Issue) on the GitHub web interface for
your own project. To solve the task, it is not
necessary to define a complicated function, but try to define a
realistic function in the context of the project (for example, add
support for emergency braking).
- [WEB] Create a development (branch) to
perform these implementation tasks.
- [CLI] Download the remote repository
(pull) and switch to the newly created branch
(checkout).
- [IDE] Complete the implementation and test it in a
local runtime (
mvn test
).
- [CLI] (Commit and push) the changes to the
remote repository.
- [WEB] Based on the resulting changes, create a
pull request for your own project on the web
interface (DO NOT select the original base repository!)
so that the change can be discussed within the development team. In the
text of the pull request, write "Fix #1", indicating that bug
ticket 1 will be closed.
- [WEB] Examine the pull request created,
and if it is OK, accept it, read it back into the master branch, and
delete the branch used for development. (We will deal with the scanning
options provided by the pull request in the next measurement.)
- [CLI] Download the changes from the remote
repository and check them using the
git log
command.
Further information can be found here:
Merge conflict
- Figure out how to generate a merge conflict.
- [CLI] Create two new branches
(
branch-A
, branch-B
).
- [CLI] Checkout
branch-A
, edit one line
in a file and commit the changes.
- [CLI] Checkout
branch-B
, edit the same
line in the same file on a different way and commit the changes.
- [CLI] Switch back to the master branch and merge
branch-A
and branch-B
afterwards. Check the
results and if a merge conflict occurs, then resolve it.
GitHub Actions
We compile and test the project in our own Git repository using
GitHub Actions.
- [WEB] Open the project in your
GitHub repository.
- [WEB] Click Settings.
- [WEB] In the Actions/General menu
on the left, select the Read and write permissions
option from the Workflow permissions options. Save your
changes.
- [WEB] In the Code security and
analysis menu on the left, enable the Dependency
graph option by pressing the Enable
button.
- [WEB] Open the Actions tab of the
project.
- [WEB] Select the 'Java with Maven'
workflow from the options offered. This will bring up an interface where
you can edit the
maven.yml
file created based on the
sample.
- [WEB] Check the
yml
(YAML) file to see if JDK 11 is set for
compiling! For syntax help, see https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-java-with-maven.
- [WEB] When you are finished, click the 'Start
commit' button to finalize the file. In principle, this will start an
instance of the created Actions workflow. Track the progress of your
workflow on the Actions page.
- [WEB] Interpret the result of the compilation on
the Actions interface (detailed log files can be accessed by clicking on
the name of the commit, look for the 'Build with Maven' step within the
build task).
- [IDE and WEB] Make some modification to cause a
compilation error. Commit and upload your changes, then check the
results on the Actions page.
- [IDE] Fix the compilation error and then add a new
unit test to the project.
- [IDE and WEB] Finalize and upload your changes,
then check the results on the Actions page.
Add external dependencies
- [IDE] Implement a tachograph module
that records the following values to a single collection. Use the Google
Guava library's
Table
class to implement the collection.
- current time
- joystick position
- reference speed
- [IDE] Go to http://mvnrepository.com or http://search.maven.org/
and search for the
guava
dependency.
- [IDE] Add the found dependency to the maven
project.
- [IDE] Create a simple unit test that checks if
elements are included in the collection.
- [IDE and WEB] Finalize and upload your changes,
then check the results on the Actions page.
Implement
additional GitHub Actions CI workflow (iMSC)
Now that the build is running successfully on the GitHub Actions CI
server, there are a few more things to set up.
- The Maven output in the CI server log is difficult to read due to
the many dependency download messages. Add the
--no-transfer-progress
option to the mvn
command. Has the log become more readable?
- Specify to cache Maven products (e.g. downloaded dependencies): description.
Finishing the lab
Commit all changes, upload to the remote repository, and verify that
the GitHub Actions runs correctly.
Important: Do not delete your own GitHub repository,
you will also work on it in further laboratories.