search

AnssiR66 / AlanStdLib

The Standard Library for ALAN Interactive Fiction Language
Other
5 stars 2 forks source link

2.2 Dev: Repository Structure Discussion #71

Closed tajmone closed 2 years ago

tajmone commented 5 years ago

Commits for this topic are handled in the dev-2.2.0-repo-structure branch.

Release 2.2 could benefit from a reorganization of the repository structure in better organized folders and assets distribution.

tajmone commented 5 years ago

Current Structure

This is the current state of the repository contents:

/extras/
    /css/
    clothing-01-simple.alan
    Clothing_Guide.html
    README.md
/extras_src/
/tests/
.gitattributes
.gitignore
ALAN Library2.1 manual.pdf
Changelog.txt
COPYING.txt
library.i
lib_classes.i
lib_definitions.i
lib_locations.i
lib_messages.i
lib_verbs.i
mygame_import.i
newgame.a3c
newgame.alan
QuickRef.txt
QuickStart.docx
README.md
readme.txt
testgame.a3c
testgame.alan
testgame.ifid

Proposed Changes

I suggest we subfolder assets by category, to make the repository more accessible (especialy to scripts and API-based web services). An initial proposal would be:

/_dev-src/                 <-- renamed: /"extras_src"/
/_tests/                   <-- renamed: /"tests"/
/demos/
    testgame.a3c
    testgame.alan
    testgame.ifid
/help/                     <-- renamed: /"extras"/
    /css/                  <-- (this folder will be removed soon!)
    clothing-01-simple.alan
    Clothing_Guide.html
    README.md
    ALAN Library2.1 manual.pdf
    QuickRef.txt
    QuickStart.docx
/StdLib/
    CHANGELOG               <-- renamed: "Changelog.txt"
    COPYING                 <-- renamed: "COPYING.txt"
    README.md               <-- convert: "readme.txt"
    library.i
    lib_classes.i
    lib_definitions.i
    lib_locations.i
    lib_messages.i
    lib_verbs.i
    mygame_import.i
    newgame.alan
.gitattributes
.gitignore
README.md

delete:

NOTE — I've proposed naming /help/ the documents folder, and not /docs/ because the /docs/ folder is a special folder in GitHub, which can be used to serve contents for the repository website via GitHub Pages. So I though that we should leave that option open, in case in the future we decide to associate to the repository a presentation website, or create an online version of the HTML documentation.

Exclude Dev Contents

It's possible to use .gitattributes to exclude some files and folders from Zip archives created on GitHub web interface when clicking on the "download" button, and also present in the releases pages (a Zip archive being available for each release). Git allows attributes to control what should be excluded from "exporting".

While this wouldn't affect the repository cloned via Git, it would allow non-Git users who are only interested in the getting a copy of the Library to get an archive without the developer and Git-related files. E.g. we could exclude from the autogenerated Zips:

When they unpack the downloaded Zip they'll be getting a much cleaner version, with only the files useful for creating adventures (and non of the maintainance scripts, the test suite, the docs sources, etc.). Also, excluding the hideen .git folder would reduce size noticeable, since it contains the index database with all the repository history.

The discussion on excluding dev contents from exported Zip files is discussed in #73.

tajmone commented 5 years ago

The StdLib/ Folder

Of all the above proposals, the one I'd like to implement first is moving the library sources to the StdLib/ folder, the others could be postponed to a later stage.

This would be a change affecting all the automated scripts (test suite, documentation, etc.) for I'd have to tweak the import paths. For this reason, it would be better to do it before starting to work on separate branches, otherwise it might get messy to merge them after.

AnssiR66 commented 5 years ago

Yes, this is ok.

tajmone commented 5 years ago

About newgame.a3c

When I moved the library files to StdLib/ folder, the newgame.a3c compiled adventure automatically got excluded from the repository due to the .gitignore rules.

But I've noticed that this binary file is actually mentioned in the readme.txt file:

ther files in this distribution package are:
[...]
- newgame.alan: a basic, barebone game source file which you can use as a
    starting point for a new game
- newgame.a3c: the compiled game file based on the above

So, should I add an exception rule and keep it in the folder?

I'm not sure what purpose it serves, newgame.alan being just a template. But if we decide to keep it (which is not a problem) we should at least make sure it gets compiled with the current library version at each release, so I might add its compilation to the update script.

AnssiR66 commented 5 years ago

If it's not a problem to keep the .a3c file, we could just keep it... but if it's more complicated than it's worth, to keep it compiled as the latest version at all times, it is not a crucial thing to keep; the .alan file is enough, too.

tajmone commented 5 years ago

If it's not a problem to keep the .a3c file, we could just keep it...

No complication at all! I had just relized that the .gitingore rules were removing the moved binaries from the project (the old ones where kept because they were there before the .gitingore file).

I just thought that if we do keep them we should also update them, just for consistency sake.

but if it's more complicated than it's worth, to keep it compiled as the latest version at all times, it is not a crucial thing to keep; the .alan file is enough, too.

Not complicated at all, just a small batch script. I was more worried about this extra script confusing end-users and cluttering the folder, so I thought it should be hidden from exported ZIP archives.

After all, these binary adventures are smaller in size than the average PDF file, or a large image. It's not like we're speaking of a huge binary file.

tajmone commented 5 years ago

StdLib/UPDATE.bat

I've added the maintainers' batch script StdLib/UPDATE.bat to recompile the newgame.alan and testgame.alan adventures.

Due to the project configuration, these adventures are actually being compiled with the Alan dev-snaphot SDK (same used for tests), and not with the latest stable release. Hopefully this is not going to be a problem.

I'll be adding the UPDATE.bat script to the list of export excluded files.

tajmone commented 2 years ago

Closing This Issue

Most of the stuff discussed here has either been taken care of, become part of the new workflow, or is rendered obsolete by the adoption of new tools (e.g. Rake) which are going to move the repository structure and toolchain closer to how other ALAN repositories work.