Readme Files on every project repository

Just my opinion here but I have been looking at some of the repository of some apps on kde lately but there is a sever lack of documentation everywhere. For example a popular app like discover doesn’t even have a readme file in the and that seems like actively maintained as well.

Honestly I think this is the big reason a lot of beginner like me feel intimidated because there is no easy way to get into anything. According to me a Readme file with proper instruction about how to build the apps and details about the dev environment is an absolute must considering it is written in C++.

The readme file doesn’t even have to be anything detailed of how things work. Just basic dev environment setup or basic building process which assume no prior knowledge of the person reading it in KDE framework is an absolute must in every at least well maintained repository. A person trying to contribute should not have to learn how entire KDE development environment function just for changing a line in QML code which may be causing a bug. Also I think newer apps should have a readme file mandatory with basic building setup for anyone to have much easier time getting into it.

These are just my opinion. But I have no experience in KDE apps so would love to know others thoughts on this. :slight_smile:

1 Like

This is something I’ve been pushing for and wanting to do for a while, but it’s not a huge target for developers. If you or anyone else has any experience with Markdown, it would be really easy to open a merge request and you can do it all within GitLab I’m pretty sure :slight_smile: Adding screenshots to existing READMEs is also appreciated.

3 Likes

We definitely need to be better about having README files in our repos.

But there’s a reason why our “how to build stuff” documentation is centralized, rather than per-repo; it’s because KDE software all generally builds the same way, so it would be terribly redundant to read the same general instructions 500 times.

Even if each repo’s README file simply said, “run kdesrc-build [repo name]”, this would fail 99% of the time because you haven’t done the requisite setup process of having recent enough Qt or Frameworks versions installed, having the required build dependencies, installed, etc. The only people for whom this command would work immediately are arch users who already have the app they want to build installed locally from Arch repos.

Arguably this is an issue with kdesrc-build; it should take care of more things for you when you run it in a not-quite-fully-set-up state yet. And it would be great to improve that. But it’s written in Perl and it’s highly technical and it’s tough to find people willing to work on it. This is the kind of thing where concrete contributions can make a real difference. Be the change you want to see in the world. :slight_smile:

We should propably standardize a bit our readme and have a generic text in each readme with a link pointing to the get involved documentation.

Alternatively we push for https://apps.kde.org/ being the real homepage of the apps instead of the invent page. It wouldn’t be an issue to add the get involved text there for each app and we already have a download section, screenshots and a summary of the application.

The problem with links in readmes is, that they tend to go stale, if not properly maintained. If any link changes this would result in a very similar merge request on every KDE Repository.

Plus links require internet access. While internet access is becoming more common, I imagine there are users out there that take a snapshot of a git repo and then compile it later at home where they might not have internet access. This is where the README file would excel. I always though this was a good README: Marcello Di Guglielmo / VNC Screen · GitLab

I always though this was a good README: Marcello > Di Guglielmo / VNC Screen · GitLab 1

This is a great example. I like it that it has some Screenshots in there.

1 Like

I think if the choice is between a link that may go stale and copying most of that get involved into every readme the link is the lesser of two evils here.

I would also point out that a change to the kdesrc-build process would lead to a patch on every readme if we put the full text in there which would be way worse than changing a link so that option isn’t without maintenance either.

1 Like

I just found this thread again and happy to report we have a lot more READMEs now and hope I can continue adding more (or inspiring others) :slight_smile:

1 Like