DEV Community

Cover image for Files every open-source project should have

Files every open-source project should have

Saad Irfan on June 30, 2021

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...
Collapse
 
barelyhuman profile image
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.

Collapse
 
msaaddev profile image
Saad Irfan • Edited

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.

Collapse
 
barelyhuman profile image
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

Collapse
 
abhinav1217 profile image
Abhinav Kulshreshtha • Edited

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
Enter fullscreen mode Exit fullscreen mode

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.

Collapse
 
msaaddev profile image
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

Collapse
 
aohorodnyk profile image
Anton Ohorodnyk

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

Collapse
 
stefannastic profile image
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-...

Collapse
 
msaaddev profile image
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.

Collapse
 
stefannastic profile image
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?

Thread Thread
 
msaaddev profile image
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.

Thread Thread
 
stefannastic profile image
Stefan Nastic

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

Collapse
 
miniscruff profile image
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.

Collapse
 
ianturton profile image
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.

Collapse
 
msaaddev profile image
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 ✌🏻

Collapse
 
mistycoruscate profile image
mistycoruscate

very informative

Collapse
 
avantar profile image
Krzysztof Szala

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

Collapse
 
msaaddev profile image
Saad Irfan • Edited

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).

Collapse
 
Sloan, the sloth mascot
Comment deleted
Collapse
 
msaaddev profile image
Saad Irfan • Edited

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. 🙌🏻