91.team-project-problems-and-solutions.md

Problems and Solutions in Team Project Development

The terms individual development and team development should already sound familiar. Individual development means one person controls all parts of a product. Team development means several people group together and complete the development of a product. To carry out team development, the following points are indispensable:

1. Manage and share events in the development process, such as who completed what and by what time.
2. Share work results, newly learned knowledge, and technical skills inside the team.
3. Manage changes to work results so existing results are not damaged, while different members can still work in parallel on top of the current project state.
4. Prove that the software produced by the team can run normally at any time.
5. Use automated workflows so team members can carry out development, testing, and deployment correctly.

Common Problems in Team Development

Compared with individual development, team development easily runs into the following problems.

Problem 1: Traditional communication cannot establish priority clearly

For example, if the team communicates through email, too many messages may bury important ones. The state of issues cannot be managed clearly, and it becomes hard to tell which problems have already been solved and which are still pending. Searching old mail in full-text form is also inefficient.

Solution: use a defect-management tool.

Problem 2: There is no environment that can be used for verification

For example, after receiving a fault report from the production system, it may take a long time to reproduce the production environment.

Solution: implement continuous delivery.

Problem 3: Project branches are managed through alias directories

Solution: implement version control.

Problem 4: Rebuilding the database is very difficult

For example, the table structure in production and development may not be consistent, or even the column order of a table may differ.

Solution: implement version control.

Problem 5: Problems cannot be discovered unless the system is run

For example, fixing one bug may introduce another bug or cause regression. Incorrect use of the version-control system may overwrite someone else’s changes, and different modifications may interfere with each other. If such issues are not discovered early, tracing them back months later becomes very troublesome.

Solution: implement continuous integration and build and test the team’s work results often and continuously.

Problem 6: One member’s code overwrites another member’s fix

Solution: implement version control.

Problem 7: Refactoring cannot be carried out safely

Refactoring means adjusting the internal structure of code without changing the produced result, but refactoring may still introduce regression.

Solution: large numbers of reusable tests and continuous integration.

Problem 8: Bug-fix time cannot be tracked and regressions cannot be traced

Solution: version control, defect management, and continuous integration should interact with each other, and ideally they should also integrate with automated deployment tools.

Problem 9: The release process is too complicated

Solution: implement continuous delivery.

After looking at the above issues, we can draw a simple conclusion: in team development, version control, defect management, and continuous integration are all very important and cannot be omitted.

Version Control

From the problems above, we can reach a simple conclusion: version control is the first prerequisite for team development. We must use version control to manage all kinds of information produced during product development, including:

1. Code.
2. Requirement and design documents.
3. Database schemas and initial data.
4. Configuration files.
5. Dependency definitions for libraries.

An Introduction to Git

Git is an open-source distributed version-control system born in 2005. It was originally developed by Linus Torvalds, the father of Linux, to help manage Linux kernel development. Unlike common version-control tools such as Subversion, Git uses a distributed version-control model, so version-control work can still be done even without support from a central server.

For people who have used SVN, Git and SVN share an important idea: both abandoned the old lock-based version-control model and adopted a more efficient merge-based model. Their main differences are:

1. Git is distributed, while SVN is centralized and depends on a central server.
2. Git stores content as metadata snapshots, while SVN manages version metadata through .svn directories.
3. Git branches are handled very differently from SVN branches.
4. Git has no global revision number, though version tags can be maintained.
5. Git uses SHA-1 hashing to protect content integrity, which gives it strong guarantees against repository corruption.

In short, Git is really excellent!!!

Installing Git

You can find a Git download link for your own operating system on the official Git website and install it. Installing Git on macOS and Windows is very simple. On Linux, if you want to install the latest official version, it is recommended to build and install it from the official source code. The steps below use CentOS as an example.

Download the Git source-code archive.

wget https://mirrors.edge.kernel.org/pub/software/scm/git/git-2.23.0.tar.xz

Extract the archive.

xz -d git-2.23.0.tar.xz
tar -xvf git-2.23.0.tar

Install the low-level dependency library.

yum -y install libcurl-devel

Note: Without this dependency library, Git network features will not work.

Configure before installation.

cd git-2.23.0
./configure --prefix=/usr/local

Build and install.

make && make install

After installation succeeds, you can type the command below in the terminal to check your Git version.

git --version

If you have never used Git before, it is worth reading a beginner guide first and getting a rough understanding of the workflow, such as git - the simple guide.

Local Git Operations

You can turn a folder into a Git repository with:

git init

After you finish the operation above, the local directory becomes like this: the left side of the figure below is your working directory, and the right side is your local repository. The middle part is the staging area between the working directory and the local repository.

Tip: If you use ls -la to view all files, you will find that after running the command above, there is one more hidden folder named .git in the directory. This is the local Git repository.

After that, the local directory includes:

• the working directory;
• the staging area between the working directory and the local repository;
• the local .git repository.

You can add one file or all files into the staging area:

git add <file>
git add .

You can then inspect the state of the working tree, staging area, and local repository:

git status

If you need to restore changes in the working tree from the staged state, you can use:

git restore <file>
git restore .

Tip: If you do not want to add a file to the staging area, you can follow the hint and use git rm --cached <file> to put the file back into the working directory.

If this is your first time using Git, you should configure your username and email before committing:

git config --global user.name "jackfrued"
git config --global user.email "jackfrued@126.com"

Tip: You can use git config --list to view Git configuration information.

Then you can commit:

git commit -m 'description of this commit'

You can view commit history with:

git log
git log --graph --oneline --abbrev-commit

Remote Git Operations

Even though Git can work locally, a central Git server is still necessary in enterprise collaboration. Companies may use hosted services such as GitHub or build their own private Git server, often with GitLab.

With a Git server in place, remote operations let you push your own work and pull work from others. For example:

git remote add origin git@gitee.com:jackfrued/python.git
git push -u origin master:master
git pull origin master

The key point is simple: version control is not just a code backup tool. In team projects it is the foundation for parallel development, traceability, collaboration, and controlled release.

Git Branch Operations

1. Create and switch branches. The commands below create a branch named dev and switch to it.

git branch <branch-name>
git switch <branch-name>

or

git switch -c <branch-name>

2. Associate a local branch with a remote branch.

git branch --set-upstream-to origin/develop
git branch --set-upstream-to origin/develop <branch-name>
git branch --track <branch-name> origin/develop
git branch --unset-upstream <branch-name>

3. Merge branches. After development is finished on the dev branch, if we want to merge it into master, we can switch back to master and use git merge.

git switch master
git merge --no-ff dev

By default, git merge uses fast-forward merge. If you want to keep the branch history, you can use --no-ff. If a conflict happens, Git will ask you to fix the conflict and commit again after the conflict is resolved.

4. Rebase branches. After many merges, branches can become messy and complicated. To solve this, we can use git rebase.

git rebase master
git switch master
git merge dev

5. Delete branches.

git branch -d <branch-name>
git branch -D <branch-name>
git push origin --delete develop

Other Git Operations

1. git fetch: downloads all changes from the remote repository.
2. git diff: compares differences between the working tree, the staging area, the repository, or two branches.
3. git stash: temporarily saves changes in the working tree and staging area.

git stash
git stash list
git stash pop

4. git reset: goes back to a specified version.

5. git cherry-pick: picks one commit from another branch and brings it into the current branch as a new commit.
6. git revert: reverts a commit.
7. git tag: is often used to view or add a tag.

Git Workflow

Since Git is an essential tool for team development, there must also be a standard workflow in team collaboration. Otherwise, even if the tool is powerful, team members will still work in disorder and conflicts will be everywhere.

Github-flow

1. Clone the code from the server to local.

git clone git@gitee.com:jackfrued/python.git

2. Create and switch to your own branch.

git switch -c <branch-name>

3. Develop on your own branch and do local version control there.
4. Push your own branch to the server.

git push origin <branch-name>

5. Create a Pull Request or Merge Request online, asking to merge your work into master.

This branch-management strategy is called github-flow or the PR flow. It is very simple and easy to understand. Its weak point is also obvious: the master branch is usually the current online code, but sometimes work merged into master is not ready to be released immediately.

Git-flow

Besides github-flow, there is another branch-management strategy called git-flow. It is also a workflow many companies are willing to use.

In this model, the project has two long-lived branches, master and develop. The other branches are temporary support branches, including feature, release, and hotfix.

1. Create a feature branch from develop, and after the work is done merge it back to develop.

git switch -c feature/user develop
git checkout develop
git merge --no-ff feature/user
git branch -d feature/user
git push origin develop

2. Create a release branch from develop, and after the release is finished merge it back to both master and develop.

git checkout -b release-0.1 develop
git push -u origin release-0.1
git checkout master
git merge --no-ff release-0.1
git push
git checkout develop
git merge --no-ff release-0.1
git push
git branch -d release-0.1
git push --delete release-0.1
git tag v0.1 master
git push --tags

3. Create a hotfix branch from master, and after the bug is fixed merge it back to both master and develop.

git checkout -b hotfix-0.1.1 master
git push -u origin hotfix-0.1.1
git checkout master
git merge --no-ff hotfix-0.1.1
git push
git checkout develop
git merge --no-ff hotfix-0.1.1
git push
git branch -d hotfix-0.1.1
git push --delete hotfix-0.1.1
git tag v0.1.1 master
git push --tags

Git-flow makes branch status easier to control, but it is much more complex than github-flow. So in real work, people often use graphical Git tools or dedicated helpers to simplify the process.

Defect Management

Without good team-management tools, project progress will definitely become difficult, and task management will be hard. A defect-management system can solve these problems. Usually, such a system has the following functions:

1. Task management.
2. Clear and searchable history of past problems.
3. Unified management and sharing of information.
4. Generation of different reports.
5. Integration with other systems and expandability.

ZenTao

ZenTao is a professional Chinese project-management tool. It is not only a defect-management tool. It provides complete software life-cycle management functions and supports Scrum agile development.

The article uses CentOS Linux as an example to show how to install ZenTao with the official all-in-one package:

cd /opt
wget http://dl.cnezsoft.com/zentao/pro8.5.2/ZenTaoPMS.pro8.5.2.zbox_64.tar.gz
gunzip ZenTaoPMS.pro8.5.2.zbox_64.tar.gz
tar -xvf ZenTaoPMS.pro8.5.2.zbox_64.tar
/opt/zbox/zbox -ap 8080 -mp 3307
/opt/zbox/zbox start

After installation, you can open the browser and visit the server to use ZenTao. The default admin account is admin, and the password is 123456.

GitLab

Code-hosting platforms and private Git servers such as GitLab also provide defect-management functions. When we want to report a bug, we can create a new issue ticket.

When creating an issue, we should usually include:

1. the software version and environment where the bug appears;
2. stable reproduction steps;
3. the expected behavior and the actual behavior;
4. optionally, our own guess about the reason for the bug.

Some agile teams also use issue tickets to manage product requirements. This is called issue-driven development.

Other Products

Besides ZenTao and GitLab, JIRA, Redmine, and Backlog are also good defect-management systems.

Continuous Integration

To produce high-quality software quickly, continuous integration (CI) is a very important part of team development. CI means letting the computer automatically repeat compilation, testing, reporting, and similar work any number of times. Through CI, developers can find problems earlier and reduce the risks caused by human mistakes.

CI brings version control, automated build, and code testing together, and turns them into an automated and collaborative process. Because it frequently repeats the whole development process, it helps developers discover problems early.

Among CI tools, Jenkins and TravisCI are very representative. The figure below shows the Jenkins work panel.

For a language like Python, CI is more often used to connect version control and trigger automatic tests and generate reports. Similar functions can also be completed by configuring Webhook.

Note:

1. Some illustrations in this chapter come from the NetEase Cloud Classroom course Everyone Can Use Git.