What I Have

I have several projects; all the files pertaining to each are kept in some ~/projects/someproject/ and broken into several subfolders. For purposes of this node, please let us say lib/ to mean ~/projects/someproject/lib/.

Most of my project files are tracked by Git; I have put a number of subfolders in hold/, which is untracked. (Formerly, I had several untracked folders but now I think it's simpler to keep anything untracked in a single top-level folder.)

I have many tests: unit tests, integration tests, author tests, user tests, good tests, bad tests. Some tests do not pass now but will later; some tests examine the execution environment and bail out of further testing if prerequisites are not installed. Some tests are useful during development but are strictly optional for user. Some tests are failed testing efforts; they may later become good tests or may stay in the junk box.

I have many notes files. Some document mainline progress on the project. Some are little snippets of CB in which somebody was kind enough to suggest a feature or level a criticism I ought to remember. Some are semi-formal documents outlining how I branch, when, and why. Some are specifically demanded by CPAN, such as Changes.

I have many tarballs. There are tarballs of related and unrelated modules, other author's stuff, that I want to poke around in. There are tarballs of the current project, one for each version released. I really need to keep tarballs in hold/, since Git does not respect mtime and I consider that little bit of metadata to be of some importance.

In fact, while I love most everything about Git, this tendency to reset mtime blandly, when switching branches, is a real annoyance. I rely on mtime to tell me something about a file; I think chronologically.

I have modules; currently, I keep them in lib/. Some of them are project modules; these are the important ones. Some are... other things. For instance, in the case of a module-testing project, there might be a "teddy bear" module which does nothing useful but can be hacked up in various ways, to act as an object of the project. I don't want to ship that.

I have scripts. For some projects, these may be CGI scripts. Another project has a script as the main command line point of entry. Some scripts are what-ifs for my own interest only; some are semi-public demos; some are utilities I expect other devs might use.

I have graphics files. Some are ready to serve on a web site. Some are graphical notes. Some are huge sets of workfiles.

This is by no means a complete list. I've tried, several times, to explain what I do currently and it's wasted effort. It's clear that I'm doing things in such a nonstandard way that it's just a confusing explanation. Please don't ask why I would have this or that; surely its enough that I do. Some of us use the Trash ruthlessly; some of us are pack rats. I don't like to throw anything away; it may become useful later.

Again, so there's no mistake: There's no point at all in addressing a single aspect out of all this. It's not of much importance how I do things now. I'm trying to find out how others do this stuff. I'm only describing this stuff in detail so you can understand exactly what kind of stuff I worry about.

Where Stuff Goes

If I just wrote stuff in the project folder and executed it directly from there, it wouldn't really matter how I organized it. But files need to move. I've identified at least six different places where a project may exist; in some sense, these are all copies of one another. A major issue for me is figuring out a structure that meets all needs or at least can be converted in straightforward fashion from one to the next.

• Local development: This is the project folder we've been discussing.
• Local deployment: Similar to user deployment but there may be some oddities.
• Remote development: I run, say, a web application on remotehost and see what it does. It usually doesn't, so I edit a local file, upload that, and try again. I don't build a whole tarball and go through the entire install process remotely for each tiny fix.
• GitHub: Periodically, I push my Git repo to GitHub. Now, I have to meet some minimal set of other people's expectations. I'm not even certain what these are.
• CPAN tarball: Eventually, I want to wrap it up. I'm using Module::Build. This process requires a whole set of files that seem to have nothing to do with previous demands. And locations are important.
• User deployment: I like to hope that my work will be of value to others. If so, well, it has to be organized just so.

Personal Quirks

There are things I like, some very strongly. I can bend on some but I'm looking for solutions that don't go too far out of my comfort zone. Please don't say these are silly quirks; all quirks are silly. My Pop wore bow ties to work every day of his life.

I don't like to mix files and folders inside a folder. That is, either let the folder contain only files; or only subfolders.

I like short identifiers, which includes path part names. I strongly dislike mixed case.

I want to keep like with like. Closely related items should be in the same subfolder. Loosely related items should be in subfolders of the same folder, and so forth.

I don't want to spend more time managing my project than I spend writing Perl.

I must avoid reshuffling my project organization; it's destructive. I need something stable.

I need a solution for each possible file transfer. Given the six states I show above, I conceive of about eight or nine possible moves.

I'm looking for the total package, not a series of roll-your-own components. I lack the experience to know what is meant to work with what.

Although I'm a solo developer, I want to keep firmly in mind a play-along attitude. I don't want to put off possible collaborators by doing things in a weird way.

I have read so much POD over the last few months that my eyes are bloody. This is like barbecue sauce: Everyone has his own recipie and nobody wants to share his with anyone else. A million patent bottles of magic clamor for my business but they're all ingredients, not end products. There are plenty of vague generalizations and tantilizing glimpses but no complete end-to-end explanations. I'm looking for the exception.

What I want is nothing less than a single, coherent guide to project management: How to organize files in my local project folder and how to get them from there to everywhere else they need to go. One word answers, such as "Try Dist::Zilla", are completely off the mark.

So, the reply I seek contains a single reference to a comprehensive work on the overall topic. I can tolerate some choices among methods but they need to be clear alternatives. I'll open my wallet if I must but I do desperately want to get back to writing Perl.