Inca Best Practices

Outlined in this document are guidelines for Incas to follow when contributing to our GitLab projects.

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, Keybase, 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 Keybase 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 whenver you approach a new task. It is important to get to the MVP stage as soon as possible and iterate often!

1. Functional Requirments (business goals)
2. Technical Requirments (what it takes to achive business goals)
3. Minimum Valuable Product (MVP)
4. Small Iterations

Issue Guidelines

Issues are a core part of the development process. Always create an issue for things you work on.

Issues need to have at least the following fields included: 1. A brief description, with relevant links and associated issues 1. Inclusion of relevant people (@ them if they are not assignees) 1. The next step or action OR an outline of the necessary steps 1. Indication about when things will be started, worked on, or completed

If there is ambiguity, you must still address these 4 criteria. For example: * If something else is required to start this issue, you should: State that is the case, link the the related task and person(s) * If you do not yet know all of the steps to complete the issue: your first steps might be to research or ask how to break it down

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 your 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 often, 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 you 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 lable. Do not abuse the status::discussion lable, 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.

More info on how to use GitLab.

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.

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 take 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 the rules and guidelines in stressful situations.

Always default to the police officer approach.

Outsourcing Work

Inca promotes the 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 Keybase 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.