InnerSource in Adeo
This is the home for InnerSource within Adeo Group
- InnerSource in Adeo
- Get started with InnerSource
What is InnerSource?
InnerSource takes the lessons learned from developing open source software and applies them to the way companies develop software internally. It can be a great practice to help break down silos, encourage internal collaboration, improve software quality, accelerate new engineer on-boarding, and identify opportunities of innovation.
Get started with InnerSource
Congratulations! You are reading this because you plan to innersource your project!
How to InnerSource?
- Choose a team or create a new team in the Adeo teams section. Note: your team should be nested by some BU parent team and should not live in the root.
- Create a new repository and attach it to a team. Respect the naming guidelines.
- Add at least a README.md file to the repo (you can follow our template). Remember: your repository is open internally by default and you must not commit any secrets to the repository.
- Follow Maturity score practices bellow in order to profit the most of InnerSource
We have to use some common tools to ease collaboration and transparency. All of these tools are available from anywhere:
Required to use:
- Github: the main home of innersource.
Other available tools:
- Slack: slack is a main tool for communication between all developers inside Adeo.
- Artifactory: for your binary packages (maven, npm, docker, rpm, …). The Artifactory user guide is available here.
- Awesome Adeo Innersource: a currated list of InnerSource projects created inside Adeo.
The maturity score is a way to evaluate the reliability of a source-code. The evaluation is not very strict nor prescriptive and can be adopted organically per repository.
For example: The source-code of a “proof of concept” can have a very low level of maturity.
|README.md file *||Project has a basic README.md file providing: repository name, what, why, summary and maintainers emails. Use this template.|
|:warning: No sensitive info *||There are no sensitive materials in the source-code nor in the revision history (for example, passwords or other non-public information)|
Maturity score boosters:
|Proper description||Project has a meaningful and unique name, that follows naming conventions, description filled, basic documentation provided (use this templates)||2|
|Open backlog||Backlog of the product is open for reading and accessible for everyone with LDAP||3|
|Code conventions||Project uses consistent code conventions (with linter) and clear function/method/variable names||2|
|Code documentation||The code is clearly commented, documenting intentions and edge cases||2|
|Usage guide||Usage guide with samples and info on how to setup and/or use the project (markdown files, mkdocs or wiki)||1|
|English by default||Usage of english across the project (code, documentation, commit messages and code reviews)||1|
|Automated testing||The project makes good use of test automation (for example, unit tests, functional tests, code coverage)||3|
|Continuous integration||Automation of the tests running, build and conventions check||2|
|Contribution conventions||The project uses a consistent convention to handle contributions from it’s own team but also for external teams, I.E: pull requests, code-review and branch permissions||3|
|Maintainers||Someone is committed to managing community interactions (responding to issues, reviewing and merging pull requests). Ideally, at least two people||3|
*: Is a MUST before even considering InnerSource
Where 12 is the minimal score for a project to be featured as an InnerSource project (The cutting score may rise as the company maturity and awareness on InnerSource increase).
Maturity Score Help
This section will give you some explanations about the previous maturity score items and explain you in details how to rise you maturity score.
Security best practices
We’ve communicated many times on the importance of security and preventing pushing sensitive data to GitHub, please read our Guide to learn how to securely work with GitHub, innersource, opensource and prevent sharing credentials with anyone.
The readme files have different roles :
- README : it is the welcome page of your project. It is the first page anyone would see when landing on your project because Github/Gitlab will display it automatically. So remember it is a kind of showcase of your project which has to be clear and attractive.
- CONTRIBUTING : you need this file if you want you contributors to know how to contribute effectively to you project. You can start from the version provided in the project-template, but don’t forget to adapt it to your needs in order to save time with PRs. If another team’s code contribution does not meet the receiving TC’s specifications, the TC needs to be able to point to the contributing agreement to explain exactly why the code is being rejected.
- DEVELOPERS : this file gives extra informations for any people that would like to start developing your project : development environment setup, guidelines, conventions, …
- CODE_OF_CONDUCT : your project your law. In order to create a peaceful community, you have to enact some laws.
You can use Markdown or Asciidoc format for each of these files. Keep the filenames UPPERCASE.
An easy way to create documentation is to do passive documentation.
Passive documentation is the record of the documentation we create every day while communicating openly. For example :
- Conversations that the Trusted Committers (TCs) have while mentoring a contributor who is learning how to integrate with her codebase
- Conversations the product owners have when they are explaining their priorities to one another, or arranging them
- The connection between a piece of the code and the project stories about the code, and the live conversations about both
- Conversations in public Slack channel
- Comments in a pull request
Documentation is only useful if people can find it.
No sensitive info
You can use Gitleaks to search for secrets and keys in your git repository history. It is a script written in Go. In case of any match, please refer to dedicated Github help to remove any sensitive data found.
Branding and naming conventions
Importance of branding
Since we are open and living in the same place, it is really important to have a memorable name and logo and to not conflict with an existing project or infringe on trademarks.
Ideally, repository names should use the following format
[project-name]--[repository-name]. Some examples:
If the repository is a generic tool that is primarily designed for re-usability across multiple teams, projects and contexts, then the
[project-name]-- is optional. For example, let’s say that “omega” is a performance testing tool, than it’s name could be:
To be able to determine the origin of the repo it will be a good practice to put a tag with your business unit using the next pattern:
bu-[4 letter name]
bu-lmru bu-lmfr bu-adeo
The structure of the group is transported to the InnerSource using Teams. That’s why all repositories must be associated to a team. Currently team nesting is used to organize the repositories. That said, the first level are the Business Units. For example:
(Github Adeo Organisation) |-- Adeo Services (adeo-services) | |-- Team A (team-a) | `-- Team B (team-b) |-- Leroy Merlin France (leroy-merlin-france) | |-- LMFR - Services Platform (lmfr-services-platform) | | `-- LMFR - Services Platform - Test (lmfr-services-platform-test) | `-- LMFR - Mobile (lmfr-mobile) |-- Leroy Merlin Russia (leroy-merlin-russia) |-- Leroy Merlin Brasil (leroy-merlin-brasil) |-- Leroy Merlin Spain (leroy-merlin-spain) |-- Zodio France (zodio-france) |-- Zodio Brasil (zodio-brasil) (etc)
What InnerSource at Adeo does concretly mean?
Let’s say we have 2 teams A and B.
Team A is developing a web application that needs to consume an API developed by team B. A new feature in the web application requires to get extra data that isn’t yet handled by the API.
In classic organizations, team A should create a feature request in API project and just wait for team B to develop and test this feature. It can take some time due to many factors : prioritization, team overbooked, …
With InnerSource, team A would directly clone the API project, develop the feature, test it with provided automated testing tools and make a Pull Request to original API project. Then team B just has to review the Pull Request and merge it into its base code.
If you have any doubt how to add these fields, you can ask for a trusted committer or another person from this team to guide you in our Slack.
In this scenario team A is less dependent from team B and the feature can be quickly deployed to production.
This is just one use case and there are many others…
When should I consider InnerSource or OpenSource?
InnerSource is OpenSource in the wall of your company. You share some code with other teams working within the same company, even if these teams are from other business unit in another country. Remember that Leroy Merlin is a world-wide company.
OpenSource goes beyond the walls of your company and is open to the world.
Generally speaking, almost all projects are eligible to InnerSource. But in practice, some projects have more interest to get innersourced than others :
- reusable projects : ansible playbooks, middleware technical bases, …
- project required by other projects : APIs, …
- projects with some reusable parts as samples : spring boot/cloud configuration, mongodb integration, oauth2 integration, …
Each time you are starting a new project, just take time to ask yourself :
- Will my project give value to other teams?
- Are some parts of my project reusable or technically interesting?
If you can answer yes to one of these questions, you really have to go innersource and acquire a high maturity score. You can also check if there is a good opportunity to go OpenSource :
- Is this project part of your Business Unit core business?
- Does this project contain BU specificities or is specific to your BU?
- Could this project be used by one of our competitors to bridge the gap with us?
- Will this project show our customer data or data structure?
- Will this project include third-party components that cannot be shared?
If you get a no for each of these questions, go ahead and push it to GitHub.com. But remember that open-sourcing a project will also give you responsibilities : you will have to continue maintaining it, answer issues and check PRs. So never forget to plan time for this because these projects will represent ADEO and its Business Units on GitHub.