Over the years, our team has tried to master how to integrate with software projects in a way that does not require too much effort from the client. We have decided to compile our experience to help our future clients understand how we integrate into teams and to help our fellow developers who are just changing jobs and struggling to fit in.
How to make integration easier for everyone?
Starting a new software project is always exciting and sometimes scary, but it can also become quite frustrating without collaboration. It is important to know not only the technical aspects of the software project but also the soft skills and personalities of your new coworkers and the project’s core values. This will be a guide mainly focusing on the technicalities of fitting into a software project.
As the employer, make sure you request all the resources for your new member before they arrive at the project. If that is not possible, plan ahead to do it when they arrive. Dragging out giving them access to essential resources will only hinder your development speed. For example, write a checklist based on our guide that applies to your software project.
Make sure that you have onboarded them correctly and that they can communicate with you within the company. Microsoft Outlook? Gmail? Do they need special authentication or a hard token to reach some things? A special laptop perhaps that is provided with the company’s operating system? The IT security solutions are endless nowadays, and they are often slow to sort out, so it is important that you start in time.
Sharing the code
Where is the code located? Giving them access to the tool you use for version control is important. Think of : Github, Bitbucket, or Gitlab? Check this on the first day they arrive to make sure they can start setting up everything that they need for work.
As a developer, after you have access to the code, you can start poking around, but we recommend that you look at how the repositories work first:
- Check the pull/merge requests! Do you see any CI/CD linked with them? If you do, check what steps must be completed before someone can get the green light. What quality gates can you see? Time to ask fellow devs if there are any tricky tests that might need rerunning from time to time.
- Check what they type in a pull request(PR), is there a pattern? Do they link the story maybe in the description or is it done automatically? Do they leave screenshots or gifs to explain what the PR does?
- Whom do they add as reviewers? Are there code owners that always need to see the requests? These might also be the people you can turn to for help later.
- Ask them: Is there a test that is not linked into the CI but might be beneficial to run? Sometimes the team is just not there yet with the complete integration of quality gates.
- Do they use the issue trackers coming with the version control?
Cloud or on-prem access
When developing in the cloud, you would typically create a user for your new developer and restrict their access rights to only the ones they need. If you are in a big company, this might take a while, so if possible, try to start the process early.
As a cloud developer, you would want to try to login into the cloud platform the company uses and check the things you need for development. If the cloud also provides CLI access, set it up as well to see that everything works and you can push changes from your computer.
On-prem software might be a bit more tricky, but generally, you would like to ask where the servers are located and how you can access them. Typically you deploy such software through CI, and access it through its IP address. In the case of kubernetes, you might get away by asking someone for a kubeconfig. In most cases, you have to find the devops engineer of the team, but test engineers often have good knowledge of the system as well.
In both cases, make sure you can list some basic resources of the system and shout if you cannot.
Database access is often hard to fight for; some industries have very strict rules on who can access data and who cannot, which also often comes with a range of training and extra contracts to sign. If, as an employer, you would like to give access to the database for a new employee, make sure that you inform yourself of the steps you must take. Oftentimes developers who are not essential are not given access to certain databases, but they can still work on data that has been generated synthetically to create the feel of a real database; this raises multiple risks in the software itself, but it might be the only road to take in some cases, and as a developer, you will have to accept that.
CI/CD pipelines
It is important to give access to your developers to the CI/CD pipelines since this is how you get your code out to the customers. It is important for them to see how the code behaves when it is being freshly built and started, and they have to react quickly if something goes wrong with the code that they delivered. Some companies do not like to do that, since CI/CD sometimes contains information about the production environments. For some cases, the CI/CD access is a must-have, and you need to ask your developers to know if that is the case.
As a developer, you can find very valuable information on your CI. From the console output, you can see what command the CI runs and what the output is. Sometimes this is the place for fishing for the environment variables that you could not find in the repositories. This is also the tool that will give you the build environment if it is correctly set up and you can share that with fellow developers or the Product Owner for reviews.
Before starting a build, ensure that you know how to remove the build resources. Your best bet is a job called to clean up, but if there is no proper documentation for the jobs you can talk to the devops engineer or someone who previously used the jobs before you to see how they work.
There might be an overwhelming amount of jobs on the platform, and if that is the case, it might be worth a shot to ask someone to show you around quickly. Before you do that, however, check the ones you feel are important and try to understand them. Write up all your questions regarding the inputs and output to make the meeting go more efficiently and to make sure there are no blank spots.
Sharing the backlog
Where is the backlog located? Jira, Rally, Trello… sticky notes on a whiteboard? Although the last might be hard to work with if you hire a remote developer the rest is important to get access to. It is also important to explain to your new team member the workflows of the backlog.
- Can a developer add a bug into the backlog or should they ask the Product Owner? Or do you have a separate place for them, for example Github Issues?
- What is your ticket life-cycle? Backlog -> To-Do -> Review -> Done, or are there special phases to show the implementation to, for example, the designer or an architect?
- How do you create stories? Are they provided by the Product Owner or does the team write them in some meeting that the new developers should also attend?
- How do you size your stories? T-shirt? Fibonacci? Or you are a free spirit and use no sizing at all?
- What story types do you use? User stories are common but some teams like separate story types targeting technical debt, bugs, test debt, and user experience enhancements.
Agile processes, scrum, and kanban
If you have not yet invited your new team member to the scrum ceremonies, it is time to do so. You could also tell them in a few words how you use the ceremonies. While it might occur to you to instantly start assigning things to your new teammate, it is important to give them a few days to settle in, set up their laptop and their workflows and set up your repositories.
As a new developer, you should observe how the team utilises these ceremonies because agile, well, it is agile, and all teams adapt it differently.
- What ceremonies do they have? Backlog Refinement, Grooming, Daily Standup (or not so daily), Sprint Demo, Sprint Review, Sprint Retrospective… Product Iteration Planning?
- Sometimes the ceremonies can get out of control and overlap, if you see the team is struggling, especially if it is a fresh team, help them out by explaining what these ceremonies are and how they can be helpful. If the requirements are lacking it might be a sign to start some Grooming sessions.
As a developer, the Daily Standup is probably the first meeting you will be invited to. You can awkwardly introduce yourself and crack a few jokes, but keep in mind that this meeting is meant to be very short, so this is probably not where you will start getting the information you need, but it is important to keep an eye out on the standup: Who is leading it? How long does each developer speak? Who works on what? It might be overwhelming because this meeting is quite quick, but you can take some notes on who is the backend developer and who is the devops engineer, who does the frontend and who does the tests.
Test the communication channels
Whatever tool the team uses, it is important to check out what channels they have.
- Is there a channel where some CI bot warns you of the failing builds? Who is responsible for looking after the problems arising there? Is there a dedicated person, or anyone can pick it up?
- Is there a channel for posting code reviews?
- Where do you communicate with management, and where is the tech talk located? Is there a channel for just hanging out?
- Introduce yourself! It doesn’t need to be long, but a simple Hello can go a long way sometimes.
Checking the repositories
After you are done introducing yourself, you can dive into the code. Our company mostly deals with Node and frontend projects, but there might be a takeaway even if you aren’t a Node developer, so don’t Alt F4 just yet!
It might be worth a mention that, in most cases, you need to set up your SSH keys for version control to be able to pull the repository. But if you can’t do that yet for some reason, you can also check out the code in the web version of the Git.
Git Configuration
Before you start, check that your git config is properly set up. Have you added your name and email, have you set up the line ending in your config? Check out the list of things you can set in the git-config documentation.
A personal favourite for VsCode users:
git config –global core.editor “code –wait”
README and CODEOWNERS
Your first job in every repository is to read the README, follow it, and correct it.
You might be sent by the holy Gopher but let’s face it, readmes tend to get outdated and abandoned. It is important to update them as a new member who is just setting things up. Take out a notepad and write down every step you have to do to make things work. This will also allow you to test the CI and the pull request workflow with no risk at all, what can you break with a readme?
Another text file that can be useful is the CODEOWNERS, if this is neatly kept, you might be able to fish out some names of people you can turn to when you realise the README is outdated and you need help.
Deep dive: Check the files in the repository
The package.json file will contain common scripts you can run in the project. try out all test and linter scripts before you start working to ensure they are correctly installed.
You can also check what packages the project utilises. If any are unfamiliar to you, make sure you give them a quick read on npm or Github.
Environment variables are usually saved in a .env file and are essential for running some test scripts or building and running the code. These are also resources you would want to mention in a README, so if it is not there either, you have to ask the developers. It might be the case that the repository does not use environment variables.
Git hooks are an excellent tool for keeping your commits clean. The repositories might have hooks that run before commit or push and prevent you from committing unlinted, untested code. They might also have a convention for writing the commit messages that you must follow. So it is worth giving the hook a quick read. Some tools for hooks are husky and lefthook, if you see these in the package list, try to look for their configuration.
Check what editors the team uses. In the .gitignore having .idea and .vscode lines might mean that the team uses more editors, so be aware that you might see some formatting and linting specific to the editors if the linters and formatters are not correctly set up. (You might as well help them out with that)
Some teams prefer to commit their .vscode folder to ensure the settings are the same for everyone. This is also where they place files such as .extensions.json which can give you a list of helpful extensions to install for the project.
Different editors can be a pain. Make sure to add the necessary extensions to your editor based on the configuration files you see in the project. For VsCode users, some might be: eslint, prettier, stylelint, editorconfig. You might also need to enable format on save and specify what extension you would want to use for formatting with each file type.
Dockerfile and Jenkinsfile might tell you how the repository is built and what CI/CD steps the repository has, it might also give you a hint on how to run some of the npm scripts you found in the package.json.
If everything is in place, you did everything to ensure you don’t mess up the codebase.
Did you enjoy reading?
Let us know what you think on our Facebook page! Were you impressed with our guide and would like to try out firsthand what the integration is like? Contact us using the following form!