Transfer a Software Project

Tags:
2022 08 02 head

You developed a new digital product for an internal or external customer. Your solution is awesome.

The product is released to delighted users. Your users love your solution.

The project is now winding down and closing activities are initiated. The customer organization shall take ownership of all product related artifacts. The handover is a vital part of closing a project [1].

Your customer paid for the development and owned the produced artifacts.

You are legally bound to deliver source code, binary artifacts defining the executable application, credentials, and documentation to your customer. The ownership transfer is either an explicit part of your contract or implicit through the contract type you are working with.

Remember, a product development is a work contract.

Work contracts[2] are a legal and rather well-defined contractual item in Europe. Expected deliveries are already defined in legal texts or through jurisprudence. Your customer has the right to refuse final payment until delivery.

How can you cleanly transfer your results to your customers? How can you document the transfer process and provide an acceptance protocol?

Which steps shall you implement to delight your clients?

Migration Steps

Most development initiatives are using GitHub, GitLab or Bitbucket. The steps are the same for all these platforms.

You should deliver a consistent [3] repository to your client.

  1. Verify that the repository contains the final state of your solution.
    Talk with your developers to insure all changes are checked into the git repository.

  2. Update your licenses and copyright.
    Verify if you have to talk with your legal department.

  3. Validate continuous integration and delivery pipeline.
    Run your CI/CD pipeline and check the deliverables [4].

  4. Validate static documentation website creation [5].

  5. + Generate your static website. Use a spellchecker for orthography, and a link checker for your links.

  6. Tag the artifacts to insure traceability between your binary delivery and the source code.
    You still need an official acceptance form from your client.
    Remember to document your tagging conventions. Are you using semantic versioning?.

  7. Transfer your repository to the new organization. You should formally document the acceptance of the produced artifacts and handover of all results. Good practice is to sign the transfer protocol.
    Relinquish formally ownership of the repository and responsibility to your customer.

  8. Celebrate the successful completion of your project.

Update Your Copyrights

The chosen copyrights shall allow the new owner to take over and change all artifacts.

Repository Copyright

GitHub and GitLab strongly support the definition and publishing of the license under which the whole project is published. Examples of open source and closed source licenses are available on the Internet. Please never write your own license text for source code or documents [6]. You are not a lawyer and your text will most certainly contain legal errors or miss required statements.

Source Code Copyright

Beware that source code is often under similar copyright rules as books and pieces of art. Regular infringement laws apply if you use, copy or modify source code. Therefore, any source code file has an implicit or an explicit copyright. Good practice is to have a banner in each source file stating the short version of your copyright.

Documentation Copyright

Documentation, drawings, and sketches are also under copyright legislation. Please add your copyright to all your documents [3].

Respect the licenses of the open source components you are using.

The free software foundation and similar entities consequently sue organizations for cheating on open source licenses. Avoid losing your reputation and money by infringing copyrights.

Update Your Documentation

I strongly suggest using actual good practice documentation as static websites to publish your documentation. The huge gain is git based tracking to map a documentation set to a specific release of your solution. Auditability and tracing of the documents are implicitly provided through version management system features [7].

The transfer is more complex if your website is published under a custom domain.

You must remove your CNAME redirection in your domain record. The receiving party can create a new CNAME redirection in their domain record associated with their company.

Additional steps to validate the newly configured domain and enable SSL are well-described on the GitHub site.

  1. Register your custom domain in the GitHub pages repository.

  2. Reserve your custom domain in GitHub to block other users to steel your domain if it is once down [2]. Beware, you need to add a TXT record in your domain. Bigger companies are quite slow to process such a request.

  3. Enable HTTPS to be compliant with good practices [2]. GitHub will generate and deploy at no costs a certificate for your custom domain.

  4. Once you have created a CNAME record mapping your custom domain to the GitHub pages website address, validate your custom domain in GitHub.

  5. Test your new site to check that all configuration changes are working. Upon successful deployment, add a redirect page on your old website to support all your users who stored an old link [8].

Beware that DNS modifications need up to 24 hours to propagate. I strongly advocate performing such changes during the weekend.

Here is a simple example of a redirect page for your old website.

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="refresh" content="0; URL=https://blog.tangly.net" />
  <title>Redirect to Our New tangly Components Website</title>
</head>
<body>
  <p>This page has been moved. If you are not redirected within 3 seconds,
     click <a href="https://blog.tangly.net">Redirect to our new tangly Components website</a></p>
</body>
</html>

Update Your CI/CD Pipeline

The continuous integration and delivery pipelines [1] shall build all expected artifacts associated with the product. Ideally, the process shall follow DevOps good practices and be automated.

If not, document thoroughly the manual steps.

Transfer Your GitHub Repository

The transfer of a repository from one organization to another one is well-supported in GitHub [1]. The whole transfer process is completed in less than five minutes.

You need your credentials to log into GitHub and confirm the transfer action. The owner of the receiving organization must confirm the transfer to complete the process.

Developers shall update their git repository remote definition in their local repository.

  git remote -v (1)
  git remote set-url origin-github git@github.com:repository-name.git (2)
  git remote -v (3)
1 List all the remotes of your local git repository.
2 Sets the new URL of the remote origin-github using ssh as transfer protocol.
3 Check that the changes to your remotes are correct.

Now you can pull from and push to the new location. Your remote can have a different name such as origin. Look at the URL after the remote name to identify the adequate remote.

Good Practices

Do not transfer a product with known security flaws to another party. Please correct the issues.

GitHub, SonarQube [4] and other tools provide convenient ways to detect vulnerabilities. Integrate these tools to support the delivery of an application without known vulnerabilities or OWASP smells [9].

Lessons Learnt

Development teams seldom understand the legal implications of copyright infringements. All source code files must have a clear copyright banner. Documentation artifacts shall also have an explicit copyright notice. Any files without a copyright will legally be handled as implicitly owned by the authors of the source code or documentation. The whole repository shall also carry an overall license files.

If you are using pictures in the documentation, clarify and track the copyrights of the used images.

The copyright files for used components shall be made available in the repository as requested by the authors of these components. Care should be taken to avoid mixing non-compatible licenses in the same product. Beware especially of the consequences of using a GPL or AGPL library in your product.

Tools such as GitHub or GitLab increase efficiency if you are adopting DevOps practices when working with them [2, 3, 4].

Links

References

[1] J. Humble and D. Farley, Continuous Delivery. Addison-Wesley Professional, 2010 [Online]. Available: https://www.amazon.com/dp/0321601912

[2] N. Forsgren, J. Humble, and G. Kim, Accelerate: The Science of Lean Software and DevOps. IT Revolution Press [Online]. Available: https://www.amazon.com/dp/B07B9F83WM

[3] G. Kim and N. Forsgren, DevOps Handbook, Second. IT Revolution Press, 2021 [Online]. Available: https://www.amazon.com//dp/B09G2GS39R

[4] B. Beyer, C. Jones, J. Petoff, and N. R. Murphy, Site Reliability Engineering. O’Reilly Media, Inc., 2016 [Online]. Available: https://www.amazon.com/dp/1492029505

1. The handover is most of the time implied through the contract or the corporate governance processes of your customer.
2. The German term is Werkvertrag. The French term is contrat de travail.
3. The project does not contain any merge conflicts or merge requests. All development branches are merged into the main branch and closed.
4. If your delivery and deployment pipelines still contain manual steps, please exhaustively document these steps. Include examples and check lists to reduce the risk of errors.
5. If you are not using pages as a documentation approach, document your solution and how you tag your documentation with the corresponding source code.
6. Use an official license reviewed by professional copyright lawyers.
7. You should easily identify and retrieve the source code, binary artifacts, and documentation for a specific release.
8. You also need to update your Google Analytics properties if you are using Google as a site usage analysis tool.
9. GitHub provides DependaBot [5] to handle dependency updates for various ecosystems including Python technology stack.