Inca Best Practices
Committing to GitLab
Committing to GitLab is the only way to show everyone what you are working on. It is important to wire updates every time you did something, however small it is. It allows others not only appreciate all the work you are doing, but also helps them keep you on the right track. If they see no updates from you in the past 24hr, people will assume you took a day off.
Communicating
If it’s not in GitLab, it never happened We keep all substantive conversations and discussions on GitLab, so we have the entire history of our projects in one place. All arrangements made outside of GitLab (Google Meet, Inca Water Cooler, email, etc.) are to be duplicated on GitLab. It is also essential that you reply promptly to all requests on GitLab. Generally, we are against one-on-one conversations and ask you to invite other people using Google Calendar or Inca Water Cooler chat channels. Administrative, personal, and security-sensitive conversations are an exception.
Structure One way to show other team members you value their time is to add more structure to your communication. Provide context, make lists, link issues, add labels, use milestones… Demonstrate you did research and organized your thoughts before involving other people in your issues. It’s not their job to figure out why you are doing something and whether it makes sense at all.
Have a plan However bad it might be. It’s much better to come up with a numbered steps plan and ask people to help you to improve it than make them guess or create one for you.
We expect to see your comments and commits every day, however small they are!
4-Step Principle
Follow these 4 steps whenever you approach a new task. It is important to get to the MVP stage as soon as possible and iterate often!
- Functional Requirements (business goals)
- Technical Requirements (what it takes to achieve business goals)
- Minimum Viable Product (MV)
- Small Iterations
MVP
Get to an MVP as quickly as possible. A rough mock-up with missing features is good enough. Start with building everything yourself and involve relevant colleagues as needed, relying on them only to improve specific parts of the product, rather than solving abstract problems. The idea is to have a full skeleton from day one to see the product as a whole. It will help you identify bottlenecks early, involve the right people, and provision any additional resources in advance. A working MVP will also allow you to leverage task parallelization - multiple people can start working on improving different parts independently. Don’t expect your tasks to go as planned if you haven’t prototyped them. The worst thing that can happen is you discovering surprises in the last piece of puzzle the day before the deadline.
Priorities
Rules, guidelines, principles, people, they all have influence on what you do and how you do it. How do you figure out who to listen to and what to prioritize? Here’s the list of things to consider in the order of their importance:
- professional ethics and common sense
- company values, strategy, and goals
- your bosses and personal responsibilities/priorities
- relevant clients and colleagues
- everything/everyone else
SWAT vs Gunslingers vs Police Officers
SWAT teams show up all together in full gear no matter what. They bring enough weapons and ammo to occupy a small village. They bust doors and windows without checking if they are unlocked. They don’t care how much it costs them to arrest a pothead or to repair the damage they cause doing it.
Gunslingers think they can shoot everyone in the village by themselves. They rarely have a plan and rely on their marksmanship skills. They don’t communicate with anyone and often shoot random bystanders. Gunslingers rarely last long - they either get shot or fired.
Police officers always follow the plan and tell the dispatcher if they want to investigate something off the beaten path. They update their dispatcher on any developments. Police officers use common sense and department priorities when choosing the car to pull over. They do their research and run the license plate before approaching the vehicle. Police officers don’t write tickets together, but they often request backup to have someone cover them if the situation escalates and help each other without getting in the crossfire. Police officers are also mindful of the costs and call for air support only in critical situations. Their most valuable quality is the ability to follow rules and guidelines in stressful situations.
Always default to the police officer approach.
Issue Guidelines
Issues are a core part of the development process. Always create an issue for things you work on. If it is worth spending time on since that enables other people to see your work in real time and intervene if something doesn’t look right. You can always edit the description or close it when the problem changed to something different or was solved.
Issues need to have at least the following:
- Brief description with necessary steps to close the issue, relevant links, and associated issues .
- Assignee. It’s okay to have multiple people assigned to the issue, but pick one responsible lead person. @ other relevant people in the issue description and clearly state their role.
- Relevant labels.
- Due date.
Update your issues
You must update your issues with:
* All notes from meetings
* Who was included
* What was discussed
* Updates on work you are doing
* Merge requests associated
* Problems you are working through
* When things are completed
* Methods/techniques you are using or considering
* Questions or clarifications (tell people if you are stuck or unsure of how to proceed)
* New due dates, tags, assignees, or steps
Do not leave issues idle for a long time; they should be actionable and realistic. Keep them updated, however small the progress is. Every time you do something, successfully or not, leave a quick comment for others to see progress or the lack of thereof. If your issue stays idle for more than a week, @bill.lumbergh will come knocking on your door. Another way to avoid getting bothered by him is exempting issues by assigning status::on hold
, status::done
, or status::discussion
label. Do not abuse the status::discussion
label, any discussion issue older than a few weeks should be either moved to documentation or closed if no useful content has been generated.
If you are assigned to an issue but don’t have time to work on it, ask for help, add status::on hold
tag, or assign it to someone else. If you don’t have time to do something let people know instead of having it linger. You can use the text: “I have other priorities and can’t help with this” or “I can complete this on May 25, please let me know if that is OK”.
When someone asks about a task, give back a deadline or that you did it. Answers like: ‘will do’, ‘OK’, ‘it is on my todo list’ are not helpful. If it is an easy one, it is better to spend 2 minutes doing it and forget about it. If it might take time, you need to figure out when you’ll do it, by returning that information the other person might decide to solve it in another way if it takes too long.
When you complete the issue, add a quick comment and assign the status::done
tag so the person who opened it can double-check everything and close it. Unless you are the one who opened it, don’t close the issue yourself.
Deadlines
Always keep an eye on the due dates for project milestones and issues. It is displayed and can be edited on the right-hand panel.
If you are the one creating a milestone or an issue, always assign a due date, even when you are not sure how long it will take to complete. Those working on issues can always move the deadline later if needed. If you are working on an issue and are afraid you won’t be able to finish by the due date, let the creator know right away. It will allow them to pull additional resources to help you or adjust their roadmap.
Bill Lumbergh
Bill Lumbergh is our robotic Project Coordinator that crawls through the projects every now and then. If he notices that your issues or merge requests do not follow the rules described above, he’ll leave you a comment and a link to the rule you are breaking. Bill is a part of our team and ignoring him will get you in trouble. Treat him as you would any other team member. As his father, @evgenyd takes it personal when people don’t treat him with respect. If you don’t like something about him, he is good at accepting constructive feedback in the form of merge requests. Feel free to learn more about Bill and improve his policies and the projects he is monitoring.
Outsourcing Work
Our company promotes outsourcing of well-defined tasks in order to quickly and cheaply accomplish goals. Work can be outsourced in two main ways: (1) requesting that we pay for a service or product to accomplish the task, or (2) requesting the creation of a “bounty issue.” To request that an existing service or product is used, notify the project manager directly in the relevant issue, or communicate your thoughts within the appropriate Inca Water Cooler channel. To learn how to initiate a bounty project please see the Bounty Program Documentation
Additional Resources
- YouTube channel and blog of a former product manager at GitLab.
- Inca GitLab how-to guide
- Peer Review - our quarterly peer reviews is a great way to receive valuable feedback from your peers.