Files every open-source project should have

This is just how I like to go. Hence, I am sharing this with everyone. But if you do things differently and you don’t agree with what I have to say next then I respect your opinion.

Well, well, well! I see you are reading this post. That means you are intrigued and curious to know all the files you should have in your open-source project. Before I jump into this, I think you may also like my earlier article which you should definitely give a read if you are into Tailwind.

Tailwind CSS User? Read this!

Saad Irfan ・ Jun 24 '21

#tailwindcss #javascript #css #webdev

So that’s said, let’s jump into the highlight of this piece. Well, you see, I am not going to take much of your time. So if you just want to know the files, here is the list of them:

• .editorconfig
• .gitignore
• .prettierrc.json
• .npmrc
• License
• Code of Conduct
• Contributing
• Changelog
• Readme

I see you are still reading. That’s awesome. That means I have your undivided attention (at least I hope so). So while I have it, let me explain each of these files and why you should have them in your project.

🎩 .editorconfig

In my opinion, every open-source project should have this file. Why? Glad you asked. You are building an open-source project. You are using your code editor and that editor is configured according to your needs. Now someone else wants to contribute to your project. When they clone your repo and open it in their code editor, they will have different editor settings. And now if they open a PR, you will notice all the weird style changes in the code. 😐

This is where .editorconfig file comes into the picture. The settings that you have added to this file will ultimately be used by all the other code editors. So if you have this in your project, and someone then clones your project, they will also get a copy of this file that has all the editor settings, and if they have set indent style to spaces and you have set it to tabs then for this project, tabs will be used for indentation.

Here is an example of the contents of this file:

root = true

[*]
indent_style = tab
end_of_line = lf
trim_trailing_whitespace = true
insert_final_newline = true

Handy. Right?!

🏗 .gitignore

I am not going to explain this file much because I know you are a developer and if you are here, then you must have heard about this strange place called GitHub where all the developers put their work on display. And you must also have used git for version controlling your software.

Well if you have this file in your project then git will ignore all the files or folders you add to this file. Since you never commit your node modules to GitHub, you can just node modules inside this file and you are gold. Git will just ignore it now and you won’t see it when you write git status in your terminal. 🥂

Here is an example of the contents of this file:

node_modules/
/node_modules/

**.DS_Store*
ehthumbs.db

✨ .prettierrc.json

You need to write code that looks pretty and easy to read. Well, you can use prettier to do just this. Since I work mostly with JavaScript and Node.js for my open-source work, I always install Prettier as my dev dependency and add an additional script to my package.json file:

{
"scripts": {
        "format": "prettier --write \"./**/*.{js,json}\"",
    },

}

This script allows me to format my entire codebase using npm run format. If you carefully look at the script, you will notice that it actually contains a regular expression. You can modify it to include all the different file types you want to format.

Well, I still need to set some ground rules for Prettier to follow. Otherwise, again different code editors have different Prettier configurations set. So, in .prettierrc.json file, you define all the Prettier-related configurations. So if you run npm run format now, Prettier is going to follow this configs. ⚡️

Here is an example of the contents of this file:

{
    "trailingComma": "none",
    "singleQuote": true,
    "printWidth": 60,
    "useTabs": true,
    "tabWidth": 4,
    "semi": true
}

💥 .npmrc

If you want to set any npm-related configurations locally in your project, you can use this file to add them. For me, I just use this file to not generate a package-lock.json file. Well, because I don’t need it in production.

Here is an example of the contents of this file:

package-lock=false

🔑 License

Every and I mean EVERY open-source project should be licensed. This is a license file and the contents of it determine which license you want to use. Since I have authored more than 10 open-source tools, I often find myself going with the MIT license.

You can easily create this file by running a single command in your terminal:

npx license [license_name]

# for instance, npx license MIT

🧑🏻‍💼 Code of Conduct

This is another MUST have file for an open-source project. I think the name is quite self-explanatory. You can add a code of conduct in your project again using a single command. Just open your terminal and run this:

npx conduct

🙋🏻 Contributing

This is a markdown file that includes all the instructions that you want the potential contributors of your open-source project to follow. Everyone has different instructions. You can find the instructions that I usually go with here

‼ Changelog

Every open-source software should be properly versioned. With every new release, a new version comes in. This is another markdown file. It contains the changes that you have done across multiple versions of your project.

For instance, in version 1.0.0, you launched the beta version of your project. With version 1.1.0, you fixed a couple of bugs. Now you might want to add the changes you made to changelog.md file. So if anyone is using your tool, they can read this file and know instantly what exactly changed across a version. 💻

You can write your changelog file any way you want. Here is an example:

### v1.1.0

Fixed bug _____
Improve code of ____
Implemented feature ____

### v1.0.0

Implemented feature x that does ___
Implemented feature y that does ___
Implemented feature z that does ___

I am not going to get into how you should version your software. Maybe I will write another piece on it.

📖 Readme

I guess this is the most magical file in a project. The content you have in this file is shown in your project repository. So mainly, this file is used for documentation. And you should have great documentation if you want your project to be successful.

And there you have it, folks. These are all the files you should add to your open-source project. You can check this open-source project of mine where I have used all of these files. And while you at it, if you like it, don’t forget to star it. 😛

You can also follow me on GitHub where like many other magicians, all my magic lies.

Until next time, cheerios. 🤞🏻

Comments

[Reaper]

prettierrc.json and .npmrc in every open source project?
Glad this is just in the javascript tag or people would go crazy.

nice post.

[Saad Irfan]

Hahaha! Yeah! I mostly work with JS so .npmrc is already there for me to save the day. But .prettierrc.json can be used with any file type as far as I know. You just need to update the regular expression.

For instance, "prettier --write \"./**/*.{js,json, html, css, vue}\"" will now apply prettier configs to JS, JSON, HTML, CSS, Vue files.

[Reaper]

True
though the prettier is limited to web based formats for now, and a few other formats.
Nothing against it, but yeah, good post since it does specify things that are needed to maintain a consistent dev environment for every developer that get's onboarded to the project

[Abhinav Kulshreshtha]

For your .editorconfig, Do include following lines if you want to make sure your markdown files doesn't get messed up.

[*.{md,mdx,markdown,txt}]
        trim_trailing_whitespace = false

Also if project can expect newbies or beginner level contributors, I also prefer to set default charset to UTF-8 because sometimes on some editors on windows, its not set as default.

Another point I recently started adopting, it to set indent_size to a designated value specially if you are using spaces, because I actually prefer size 4 at least but many editors including vscode have size 2 as default which for me is too low. I also met some old school c programmers which set tab size to 8 for them.

I don't want to get into holy war tab vs spaces but recently for a new project I started setting default indent to tabs instead of spaces ( mostly because of aforementioned old school c programmers with 8 tab width having conflict with new python programmer with 2 tab width. ) with a reason given to me as "count the indentations, size of indents doesn't matter" . This dev article inspired me to do that. But in the end, it is personal preferences.

[Saad Irfan]

Hey! You are absolutely right about all this. The sample I gave is an example of contents you have in .editorconfig. Because if you look up any of my OS projects, you will find I have all these set in my .editorconfig file. But I didn't know about the markdown thingy. Thanks for that!

P.S. I also prefer tab size of 4. I have configured my VSCode to use tab size 4. :D

[Anton Ohorodnyk]

Thanks for .editorconfig file, I did not know about it, but it’s must to use!

[Stefan Nastic]

I also like the idea of standardized experience and lowering barrier of entry for developers who are keen on open source contribution. Recently, I also wrote an article about development containers. Have a look if you are interested stefannastic.medium.com/why-every-...

[Saad Irfan]

Hey! Thanks for sharing. I will definitely give it a read. In the meantime, I would suggest to move here from Medium. You will get more audience here.

[Stefan Nastic]

Thanks for the suggestion! I started fairly recently on Medium. So I would like to explore it a little longer. But I am also considering dev.to. What do you think about cross posting on both platforms or is that a bad idea?

[Saad Irfan]

Medium is kind of a generic platform as compared to dev.to. Ben has explained this in detail here. But I think doing cross-platform doesn't hurt and worth a shot.

[Stefan Nastic]

I heard the community here is great and you sir have just very much confirmed that!

[miniscruff]

Changelogs are great and often overlooked, it can be daunting and scary to document all the projects changes especially when some of them are bug fixes you caused. It is common for teams to update the changelog from memory during the release process or from an issue tracker like Jira separate from the source code which has many draw backs. Or, my least favorite thing, is when projects use commit messages as changelogs. The reason this is not so great is that, commit messages are to help developers understand what has happened in the code. But the changelog is for users to understand how the changes may or may not impact them.

To help aid in all this I recommend some sort of tool; python has blurb-it, gitlab is a ruby script, or smaller simpler tools like the one I developed Changie.

Note: If you do decide to use commit messages, make sure you follow something along the lines of coventional commits.

[Ian Turton]

It's better to specify your formatting requirements, rather than hoping that I will be using the same editor as you. By all means provide editor setup or formatter control files. But please tell me what you want so I can configure my tool chain and maybe commit it back to your project.

[Saad Irfan]

Hey! Thanks for your concern. Kindly read the very first line of this article. Also, changing your code editor settings for a single project does not seem very optimum. This just seems like grunt work to me TBH. Hence the reason why .editorconfig file exists because it works across multiple IDEs. You can read more about it here

Peace ✌🏻

[mistycoruscate]

very informative

[Krzysztof Szala]

But you know that not whole OS world is spinning around JS? ;)

[Saad Irfan]

Hey! I know. These are just personal recommendation. Hence, the note at the very top of this article. Also, I guess other than .npmrc, all the other files are quite relevant in any open-source project (not specifically JS).

[Saad Irfan]

It is more of a good practice to have them in an open-source project. If you are not using Node then you can skip .npmrc. Otherwise, each of these files hold significant importance. And I have explained this in this piece.

Hope this clears it out. 🙌🏻