When I'm processing processing peoples' submissions to our archives, by far the most common reason for rejection is that uploaders haven't followed the guidelines that are right there on the upload page. Currently, they read as such:

I find it's the first two points that are usually problematic. Many times this may be because uploaders don't believe their programs are complex enough to require any documentation, but I suspect it's also common that people simply haven't paid any attention to the guidelines. People frequently upload bare .8xp files, and even after they're rejected and I paste the guidelines from the upload page into the rejection message they sometimes still just put the file into a zip archive without any documentation!

One person did recently reach out after one of their files was rejected because it didn't include a README and asked for the reasoning behind that rule. I justified it by stating that we'd like downloaded files to be self-descriptive: once you've downloaded something it should be possible to understand what it is and how to use it, even if you don't know it originally came from Cemetech. It's also useful for newbies if you provide basic instructions on how to do things like send programs to a calculator, but I generally don't expect anybody to spend much effort on that because it's so tedious-feeling. For more complex programs, it's not reasonable to put all of the documentation in the file description on the web site so those really need a README or more in-depth documentation.

---

Since I'd like to provide that kind of reasoning in a more public place, that's one purpose of this post. But I'm also interested in ideas for ways to make it easier for uploaders to follow the rules with their uploads. I've got a few thoughts which would be various degrees of annoying:

• When validating upload form submission, check that the file is a recognized archive format and contains a file named README of any type. If either of those is not satisfied, require the user to affirm that the upload does meet the guidelines (just check a box).
  
• Automatically add some kind of metadata file to archives when uploaded ("Downloaded from cemetech.net.txt"?) that links to the file page. I don't really like this, but it's not a terrible solution to providing context to downloaders.
  
• Require uploaders to check a box for each of the guidelines to affirm their upload follows the guidelines. This would make it harder to ignore, and isn't very difficult to implement.
  
• Revise the wording of the guidelines to be clearer? I wrote them as they are now so they seem clear to me, but maybe they don't make so much sense to others. I'm open to suggestions here.

To support the "providing documentation for newbies" case I noted above, I'm also willing to explore ways to add help to file pages so people can discover how to use files without depending on the file author to write it. I imagine some kind of help link to a "how to send files to your calculator" page for whichever kind of calculator a file is for would be nice, but writing that from scratch is enough work that I'm unlikely to be bothered to do it myself anytime soon. If anybody wants to have a go at that or has resources in mind that we could copy or link to, I'm interested to see what you've got.

Just sharing my experience from TI-Planet:

Lots of people nowadays have no idea what a "zip" is, let alone "gzipped tar".
I'm also not so sure they will understand what you mean by "plain-text README file".

The rest seem OK to me.

A suggestion would be that if you don't detect an archive at all, or an archive with a README inside, when the file is dropped onto the <input>, add a <textarea required> on the form (checking a minimum amount of content before it can be submitted), and in the backend (probably) make that become the README you'd inject into the zip file (that you'd create if necessary, or just modify if the user had just a zip without a readme)

Phrasing that differently, it sounds like this would be walking the user through creating a zip and adding a README? That does seem like a neat approach to helping users do the right thing mechanically, but has fairly high implementation complexity.

Just prevent the user from submitting the form until they have met the first 2 requirements.

I don't speak web development so I don't know how difficult this would be to implement, but you could add the option after uploading a program to add a Readme in the website (i.e. you type it into a text field and it makes a .txt file from that) or maybe even the option to compress the program into a zip directly from the website. Again, I don't know how hard that would be to implement but it would probably be helpful to newbies.

P.S. I asked ChatGPT and it said both of these would be pretty easy to implement using JS, but I have absolutely no idea how accurate that assumption is : )

Any room for questioning the need for the readme files in the first place? The format of the file I get, and .zip is really not that all too uncommon. But a readme for a simple TiBASIC program that takes two or more self-explanatory inputs from the user and outputs an answer seems overkill. The reasoning that all downloaded files should be known to the user is weak and seems more to be what some people want rather than what is desirable overall. If a user has deliberately went to the Downloads section, deliberately looked up their calculator model, deliberately selected a program and deliberately downloaded it, where does the ambiguity of knowing what this file is and where it came from come into play? It has a specific proprietary file name to be easily identified.

Did you read the first post from Tari? Even if a file originally came from Cemetech, it could easily be redistributed between computers/calculators and lose that information. Personally, I've redistributed many files to friends' calculators, none of whom have even heard of Cemetech and none of whom know how to use TI Connect CE. At the bare minimum, a ReadMe could just link to the file's page and/or forum on Cemetech (although I'm guessing Tari suggests you should have more than just that).

And I understand that a simple file may not seem like it needs a ReadMe, but you should still include one anyway because you wouldn't believe how ignorant people can be. Even if a program just displays "Hello world" (and I have no idea how that would be accepted into the archives) the user still needs to know how to send that file to their calculator, what models it runs on, etc.

At the end of the day, the admins can't just cherrypick which uploads have to follow which rules; there have to be standards in place because they're generally necessary (even if once in a while they may seem like they aren't). If you say that only some files need a ReadMe, that means that any time anyone uploads any file, the admins have to inspect it closely and then decide whether or not it's worthy of not needing a ReadMe. I can't speak for them, but I'd assume they don't want to do that.

This is one of the things i'd like the most on cemetech: auto README generator.
I'm very much pushing for this (i mean, this would solve the fact you need to zip then README, which not many would know and could get frustrated bc of it).
I actually wrote one of my projects's README to be what happened so far, so that everyone knows why i think making a whole README is pointless.

I'm not gonna share the project (yet), but if someone asks for the name, i'm willing to provide it.

This sums up my thoughts exactly. I know programmers hate documentation but if a program is super simple, then it won't take long to write the Readme. 😉

I like womps idea of disabling the submit button until the first two criteria are checked. Maybe add help links on how to make a zip and a Readme document. Perhaps provide a template Readme. I remember when I uploaded my first program I thought a Readme was a special file type and I didn't understand what was supposed to go in it.

I guess Cemetech could make it easier on new uploaders by letting you upload all your calculator files to the submission form, type your Readme in a text box also on the submission form, then when you click submit Cemetech will zip everything for you. This seems like a lot of work for an admin (probably Tari) though.

Any additional documentation like a readme does not get on the calculator though. Only the relevant calculate file. So I’m not sure how your argument that program files get passed around a lot necessitates a readme.

Frankly folks were talking about calculator programs here that started at a time when the career path of software developer was not even a thing. This site should be just as much about unhindered learning of programming and the development community as it is about producing and sharing high quality programs. I think trying to cast a wide umbrella over each given consideration solely to one or the other turns the sharing I to a bit of a burden. And I get making a readme is no big deal. Heck all I did when I was told I needed for extremely simple and self explanatory programs I just sent the file to ChatGPT and said make me a readme. But being told you can’t submit unless you have this or working hard on your first simple problem and being told you have to have this essentially pointless readme file just smacks of elitism over actually welcoming and encouraging program development.

I think a good first place is to be aware that a TiBASIC program like my stopping distance one is a much different beast that something roccolox might put out. Trying to make a one sized box for both is just clunky and silly, treating them both the same is discouraging to people who are at a level many floors down from our most prolific (and amazing) assembly programmers.

I understand that. My point is, the first person to download the program may need to be guided through installing it onto their calculator, which is a universal property of all calculator programs. When I was just starting out a few years ago, I had no idea how to do anything on my calculator, let alone send programs to it from a computer. All I knew is one of my friends had Mario on his calculator and I thought that was cool, and even he didn't know how it ended up there; he just inherited it from his elder brother. I think it's a wonderful thought that some file I've uploaded to Cemetech might be the first file someone downloads onto their calculator, and therefore it ought to teach them how to download it. I want to do everything I can to help this person on their calculator journey, starting with a ReadMe.

Once the program has been downloaded by someone, if they share it to another calculator then either a) it's really self-explanatory, or b) the person has been using it for a while and knows how to explain it in depth to the recipient. At that point, the ReadMe is probably lost to time. But again, my point is that the first person to download that program might not know how to install it or use it and they need to be taught in order to teach others.

I agree wholeheartedly that Cemetech should be a place for unhindered learning, and I get that it may be discouraging for a newbie to try to upload a file and be told they need a ReadMe. But imagine how much more discouraging it is for some kid to download their first file from Cemetech, only to have no idea how to use it or even install it because there's no documentation! The time you spend making a ReadMe is much less than the time it will take for someone who's never downloaded a file before to figure out the whole installation process on their own. A ReadMe, again, could be as simple as "Go to this Cemetech link for more information." Ultimately, I just don't think it's that big of a deal to make one and this is kind of a weird hill to choose to die on.

Before any more effort is spent on discourse about this: We will not be changing this restriction.

If they don't know what a zip is, or they don't understand what "plain-text README file" means, this is the perfect opportunity to teach. It might be helpful to link to pages (or have little question-mark help text) that explain what those terms mean.

I vote for this idea.

Summarizing points so far.

Some people think READMEs shouldn't be required at all. I disagree with this and am not inclined to change that rule. I think TLM makes a good point that simple programs can have simple documentation, and might take it further and say that if a program isn't worth writing any documentation for them it's not worth publishing at all. (And that's fine! Not every program is worth sharing!) Having this reasoning written down would be helpful to help people understand the rules, but doesn't seem that important.

Next, some people may not understand what a ZIP archive or README file are. This can be improved simply by providing documentation and linking to it, probably with examples.

Finally, users may find it difficult to create a ZIP containing a README even if they understand what's expected. For instance, I have no idea how somebody who's using an iPad as a primary computing device would go about doing that. (Although the status quo appears to be that you couldn't use such a device to talk to a calculator anyway, because WebUSB isn't supported on iOS.) I suppose you could get most of the way there with a webapp like zip-manager.

Failure at any stage will tend to either make a user give up, or submit a file that will be rejected because it doesn't follow the rules. There seems to be agreement that we should automatically check for satisfied requirements, and I'm inclined toward the softer approach of asking "are you sure you followed the rules?" rather than fully blocking upload of things that aren't zips containing a README. It seems like some artifacts like documentation files are their own READMEs and wouldn't even need to be zipped, for instance. That could be simplified for users by providing some functionality that can automatically create a zip from a README the user enters directly on the page, but we could also refer them to external tools to help do so, saving us implementation and maintenance effort.