This is for discussion when developing
Closed this issue · 2 comments
This issue will be used to upload some information that developors should notice.
Statistics
matrix-calculation-accelerator
Brief Introduction
Matrix calculation implemented by C++ with multi-thread. This will implement some basic calculations of matrices, such +
, -
, *
, /
, etc.
What Can You Learn From This
Those below are what you can learn:
- The basic usages of
git
- How to write a reasonable and readable commit message
- The whole
gitflow
process - The basic usage of
cmake
- The
CI
process - How to write unit tests with
GoogleTest
- How to generate code coverage report with
lcov
- ...
Learning Materials
If you don't know how to use git
, you can read this: Version Control (git), Learn Git
If you don't know git flow
, you can read these to learn git flow: My own understanding of Gitflow, A successful Git branching model
If you don't know how to write tests through GoogleTest
, you can read this: GoogleTest Primer
If you don't know how to write commit messages, you can look at this: How to write commit messages
Here is a screenshot for rules of writing commit messages:
How to Write My Own Codes?
Once you clone the repository, you should make sure that you are on the develop
branch, you can use git checkout develop
to convert to develop
branch. After this, you'd better run git pull
to make sure the develop
branch is up to date.
Usually, you cannot commit on develop
and master
branches (You can commit locally, but you cannot push, and you can only make updates on these branches through pull request
). So if you want your codes be submitted to the repository, you can create a new branch depending on develop
( through git checkout -b new-branch-name develop
) and write your own codes on the new branch.
How to Build the Project?
If you are familiar with CMake
and GoogleTest
, you can skip this part.
Once you finish your codes on your new branch, you may need to compile the codes to make sure the codes can be compiled. Let me introduce you how to compile the project:
- Make sure you are in the root directory of the repository.
- Run
cmake -S . -B build
. - Run
cd build && cmake --build . -j64
, you can update64
with any other positive number to specify how many threads you want to use when building the project (You'd better make sure it not exceed the number of your cpu cores or cpu super-threads). If there is no any error, CONGRATULATIONS, your codes can be compiled successfully.
If you want the build process same with git actions
, you need make sure clang-tidy
is available on your computer. If you use UNIX-like
system, you can use sudo apt-get install clang-tidy
to install clang-tidy
. If you don't install clang-tidy
the codes you write may be compiled successfully locally, but may not pass the git actions
.
Although you compile your codes successfully, you should be aware of that the codes which is compiled successfully may not work properly. So you need write unit tests for the every function you write. So you need create a file which is related with your new codes. The filename usually is the origin base filename followed by _test.cpp
. If there have been already one, you just need append your unit tests codes. If you finish writing unit tests, you can re-build the project through step 1-3
above. And change you directory to build/test
(after building successfully), then run ctest --output-on-failure
, this will start run all the test units. If all the tests pass, CONGRATULATIONS, your codes may be OK. If there are some tests failed, you need check the codes you write (both test codes and the source codes), and update them to pass all the tests.
How to Submit My Codes to the Repository.
Once you finish your codes, and pass all the tests. You must run clang-format -i src/*.cpp src/include/*.h test/src/*.cpp
to format your codes automatically (make sure you are in the root directory of the repository). Then make sure all you changed have been committed localy, and make sure the commit messages are readable (meet the rules).
Now you can create a branch remotely, you can use git push origin -u your-branch-name
to push your branch to remote with the same name. After this, you can create a pull request
to merge into develop
branch ( choose the right branch). Write the title and the description. The changes will be checked by git actions
. Once it passed, you can copy the url
and send it to another collaborator to let him/her check you codes. Once the collaborator checked the changes, your codes will be in develop
branch, you can update your local develop
after this (git checkout develop; git pull
).
If you have merged the remote branch into develop
, and you are sure your branch will not be used, you are supposed to delete the remote branch created by you. You can use git push origin -d remote-branch-name
to delete a remote branch.
How to Update When I was Told?
Sometime, your codes may be add some reviews by the collaborators, you need update your codes to resolve these reviews.
You can update your local codes to meet the collaborators' suggestions. After this, you can commit, and then use git push
to update the remote branch (this will re-run git actions
). These new changes will be seen on the pull request
, if you resolve the problem, you may click the resolve
for the review.
Note: the below is not recommended.
If you think the new commit can be submitted without creating a new commit, after you update your codes, you can use git add
to add your codes, then git commit --amend
to let the new changes be in the last commit. After this, you must use git push -f
to update the remote forcedly.
When to Merge Develop Branch into Master Branch
This will depend on me. Usually, when some new features finished and tested, I'll create a release
branch to update version number and merge the release
branch into master
and develop
.
This part has been add to README.md
.