Project conventions

Binary files

Adding binary files (other than images) to the DevDocs repository goes against our project conventions. Examples of binary files that we do not store in this repository include:

• Adobe Illustrator (.ai)
• Adobe Photoshop (.psd)
• Archives (.zip)
• PDFs (.pdf)
• Microsoft Excel (.xls)
• Microsoft Word (.doc)

Policy

All downloadable binary files should be hosted external to the DevDocs site so that the owner of the file can independently update the file as needed without intervention from the devdocs-admins team. Files for closed source, licensed software are unacceptable because the DevDocs project is open source.

We currently store some downloadable binary files at https://devdocs.magento.com/downloads/, but every time a contributor updates a file it requires a member of the devdocs-admins team to upload the file manually. This location is a temporary compromise until the owners of these files can find alternative hosting solutions.

Background

In the past, contributors added binary files to this repository so that they would be available as downloads on devdocs.magento.com because they had no other place to put them; causing this repository to become a sort of dumping ground. Once uploaded to the site, these files were quickly forgotten by contributors and became outdated, used on inordinate amount of storage, and increased latency during git operations that adversely impacted CI/CD for the site.

In response, we established a new policy to force contributors to find appropriate hosting solutions for their binary files so that we could externally link to them from the DevDocs site. See pull requests #6828 and #8239.