Engineering
Software Development
Use sandbox, don't play on live systems
When we work on software development (either for Web application development or research work), we spend certain amount of time for investigation and experiments. When you want to try a new idea, it's important to isolate the place for experiments and live systems. Imagine what's gonna happen if play on a live systems. It brings us unecessary pains like;
- Messy codes or bunch of code stubs on production environment
- Accidentally affects to the production system
To avoid these issues, it's a best practice to have your own sandbox area and try new ideas there before applying it to the production codes. Only when you've confirmed that it works try to migrate it to the live systems by picking up the essential parts of them.
Sandbox can be various forms lincluding; isolated repository, directory, projects (on Google Cloud).
Repository management (Git)
Choose the right workflow for your team
How do we manage codes depends on several factors such as the type and size of project, as well as the phease.
| Factor | Example |
|---|---|
| Type | Research / End user Application |
| Size | Solo / 2-3 members / more |
| Phase | Early / Pre-release / Production |
Basically, the repository should be organized and structured more if the size of the project get bigger. On the other hands, for smaller project or early phase project, flexibility can be prioritized. Depending on these factors, choose suitable workflow for your team.
quadrantChart
title Factors to take your workflows
x-axis Small Projects --> Large Projects
y-axis Few Users --> Many Users
quadrant-1 Solid, Organized, Structured
quadrant-3 Agile, Flexible, Light
Solo Research work: [0.15, 0.1]
B2C Service: [0.8, 0.9]
B2B Service: [0.6, 0.3]
PoC: [0.4, 0.3]Use Github Flow
No matter what kind of project it is, Github Flow is a golden-standard workflow to follow, unless it's a solo project which consists only you as the developer.
For application development projects with release process involving end-users, it's recommended to follow Gitlab Flow. In this case, add production branch to your repo., in addition to the main branch, which synchronizes release version of the application.
Commit and push frequently
There are several benefits to commit & push frequently;
- You can use Github as backup place for your code
- You can roll back to previous code
- You can get feedbacks on time
- You can avoid duplicating work
Reference: Gitlab Flow
Commit often and push frequently
...
Committing often also helps you share your work, which is important so that everyone is aware of what you are working on. You should push your feature branch frequently, even when it is not yet ready for review. By sharing your work in a feature branch or a merge request, you prevent your team members from duplicating work. Sharing your work before it’s complete also allows for discussion and feedback about the changes. This feedback can help improve the code before it gets to review.
Reference: Git Commit Best Practices
Backup: In case you work on a task for several days without pushing to the central repository, you risk loosing your work in case your PC goes down (assuming you have no other backup system in place).
The timing / frequency of commit & push;
- When you have a progress, it's time to commit & push
- It's OK to push several times per day.
- You don't need to hesitate to push your work even if it's still a work in progress. You can use "[WIP]" identifier on commit log.
Maintain README.md properly and regulary
Make sure that everybody, including you, can reproduce the system by just following the steps written in Readme.md.
If you feel that the steps are too long, consider to make some scripts (Makefile, Justfile or shell script) to consolidate the steps into one simple executable command.
Test (validate) before publishing PR
Reviewers try to test your code by following the steps written in Readme.md. If something is wrong with the contents, additional communication will be needed which wasts both your time and others's time. Make sure your code works properly before publishing PR.