Maintaining an open source project is fun, full of surprises, and sometimes hard. The following tips have been gathered from experience and discussions with other maintainers.
The README.md
file is perhaps the most important file in your project. It describes what your project does.
It has an .md
extension, so it’s written in Markdown, the same language as your Swift documentation, so if you were not previously familiar with it, you should be by now.
Ideally, it should contain multiple sections:
- A title that should match the repository, folder, and package-manager names
- A short description, which is the hook, indicating what your project does, in a nutshell
- A table of contents, if your readme is very long
- Instructions for installation
- Instructions on how to use your project
- Instructions on how to contribute to the project
- The license for the code you are open sourcing
I didn’t invent those on my own, but a standard readme specification is actively...