Excluding Dev Files/Folders from Downloadable Zip

[tajmone]

Add export-ignore rules to .gitattributes file to selectively exclude maintainers/developers files and folders from the Zip archives downloadable from GitHub web interface (via the "download" button, and from the releases pages), so that end users only interested in the Library files can download a cleaner cut-down version.

Export-Ignore Rules

Decide which files and folders to excludes and add the required patterns to .gitattributes:

• [ ] ???

Reference Links

Useful links on how export-ignore rules work in Git and GitHub.

• Git documentation » gitattributes
• Git documentation » git-archive
• Using git attributes to exclude files from your release
• Use gitattributes to keep your tests out of other people’s production

[tajmone]

Markdown Docs and READMEs

I was also thinking about the various markdown README files, changelog, etc.

On the one hand, having these docs in markdown (or, even better, AsciiDoc) provides better previews when browsing the GitHub portal, for they are automatically rendered to HTML.

On the other hand, end users who download the library might not have a markdown previewer (and most unlikely an AsciiDoc previewer), so these files would look less readable when veiwed locally as plain text.

Currently, the original plaintext docs of the library are in .txt format, which is highly readable without the need of any previwer, but don't offer a nice preview on GitHub. For example, these files:

• QuickRef.txt
• Changelog.txt
• readme.txt

I was thinking that we could exploit export-ignore rules to improve both online previews and end-users documentation:

• Maintain these docs as AsciiDoc files in the repository, so we get the best formatting options and nicest online preview on GitHub.
• Add a conversion script in the folder that converts them to HTML via Asciidoctor, so end users will have a very nice document to view in the browser.
• Exclude from exporting in the Zip archive the original .asciidoc files and the conversion script, so end users get just the clean HTML document when they download the Zip copy of the library.

This way, we'll have to maintain a single source document and let the rest be handled automatically.

What do you think?

[AnssiR66]

OK, what you suggest sounds reasonable. We can use export-ignore to handle this.

[tajmone]

Text Substitutions in Zip Archives

Just for the sake of evaluating all available options...

I've discovered that when exporting a Zip archive with Git it's possible to enforce some text substitution on selected files via the export-subst attribute:

• https://git-scm.com/docs/gitattributes#_creating_an_archive
• https://git-memo.readthedocs.io/en/latest/git_archive.html

It seems a useful option to automate insertion of date and version info in various documents at release/download time.

By using content filters drivers scripts it could be even possible to get the Alan SDK version injected in these docs/files:

• https://stackoverflow.com/questions/19659976/add-tag-in-export-subst-file

The latter might require some complex setup, but I'm noting this down because it has some potential. Still, I'm not sure if these attributes would work on GitHub downloads, but it's worth looking into it.

[tajmone]

Initial Export-Ignore Rules

I've added some initial export-ignore patterns to .gitattributes:

## Git files/folders
####################
/.git/          export-ignore
.gitattributes  export-ignore
.gitconfig      export-ignore
.gitignore      export-ignore
.gitmodules     export-ignore

## Dev folders
##############
/extras_src/    export-ignore
/tests/         export-ignore

## Specific dev files
#####################
/StdLib/UPDATE.bat   export-ignore

Unfortunately, we won't be able to actually test them until we merge into master or create a release, for the download button only exports master branch, and release archives are added only when creating a tag or a manual release.

So, actual testing is postponed after squashing into master — in the worst case scenario, if tweaks are required, we could force push the changes to keep the history clean.