jasononeil / haxelib

Provisional project for the Haxe 3 related haxelib changes.

Haxelib

For documentation, please refer to haxe.org

---

Running the website for development

(Work in progress instructions, 2015-02-27)

# Initial checkout
git clone https://github.com/jasononeil/haxelib.git
git checkout feature/newsite

# Install all the libs
haxelib install newsite.hxml
haxelib git ufront-mvc https://github.com/ufront/ufront-mvc.git

# Create directories
mkdir www
mkdir www/legacy
mkdir www/api/
mkdir www/api/3.0
mkdir www/files/
mkdir www/files/3.0

# TODO: copy assets

# Compile the site
haxe site.hxml
haxe newsite.hxml

# Set up the test database
cd www
neko old.n setup

# TODO: check the permissions, writeable directories etc.

# Start the server
nekotools server -rewrite

About this repo

Build files:

• haxelib.hxml: Build the current haxelib tool from src/tools/haxelib/Main
• legacyhaxelib.hxml: Build the haxelib tool that works with Haxe 2.x
• prepare.hxml: Build a tool to prepare the server (I think)
• site.hxml: Build the old website, the legacy website, and the Haxe remoting API.
• newsite.hxml: Build the new website, the new site unit tests, and the Haxe remoting API. (Also runs the unit tests).
• test.hxml: Build the automated tests.

Folders:

• /src/: Source code for the haxelib tool and the website, including legacy versions.
• /bin/: The compile target for building the haxelib tool, legacy tool, and site preparation tool.
• /www/: The compile target (and supporting files) for the haxelib website (including legacy site and API)
• /test/: Unit test source code for running on Travis.
• /testing/: A setup for manually testing a complete setup.
• /package/: Files that are used for bundling the haxelib_client zip file.

haxelib's Issues

Responsive Design Fixes

This issue is to collect a TODO list of things to fix up when viewing the site on mobile.

Features for after launch

Create new issues later:

• Track downloads as installs
• User logins
• User password resets
• Featured libs
• Follow a project, get email alerts when they update
• Pretty graphs for usage statistics
• Any kind of user generated content / comments / upvotes etc.

Relative image links in README don't display

Can we search for relative links in MD and redirect them?

• Links from README, redirect to files/
• Images from README, redirect to raw-files/
• Images from Markdown View in files/, redirect to raw-files/

See:

• http://preview.lib.haxe.org/p/flixel-demos
• http://preview.lib.haxe.org/p/flixel-demos/1.1.1/files/README.md

Performance Considerations

With the READMEs and file browsing, we currently have extract each file from the zip as required. It might cause too much load on the server if we have a sudden rush of people. Perhaps some caching is needed, at least for the READMEs?

Also for the haxelib.json file, which I think I want to start using to grab information about dependencies, extra params etc also.

Library icon

Maybe we could add the favicon corresponding to the website URL in front of each library ? that would add a bit of graphics/colors to an otherwise black&white pages. We could also allow people to put their own icon.png in the zip but that's maybe a bit more difficult to implement ?

https://www.npmjs.com allows big icons for instance (if I look a the featured packages)

Haxelib commands

I think that the haxelib command list documentation could be made much more readable
Currently we have http://preview.lib.haxe.org/documentation/using-haxelib

We could present each "command" with a description, a bit longer than it is right now and an usage example. By using a bold+color for the command it will make it more easy to find the one that you're looking for (similar to "CLI command" section on https://docs.npmjs.com/)

Project list template doesn't have access to Owner / Version objects

This seems to be a glitch somewhere inbetween SPOD relations, our SiteDB model classes, and erazor's templating. The templates can't access the properties by a getter.

I either need to diagnose the glitch, or use a View-Model typedef similar to ProjectInfos, that has all the information relevant to the view.

Stats arent up to date?

http://lib.haxe.org/p/tink_xml/
How much time does it take before the stats are updated?

Doesn't 404 when you view a project version that doesn't exist

See http://preview.lib.haxe.org/p/cleversort/nosuchversion

It would be nice if the 404 page also had the version list, or at least a link to the current version.

All users page

Do not list downloads count in http://preview.lib.haxe.org/u/ (still sort by most downloaded) this will make the page more readable

Improved homepage

• Prettier logo, heading, jumbotron box
• Are we happy with the lead paragraph / description?
• We have browse by tag / user / popularity etc. What about search?
• Usage examples box is too tall. Are there any lines we can cut?
• Featured project - make it a real feature or get rid of it.

Prevent google crawling, or make it faster.

We just had a google bot start crawling "preview.lib.haxe.org". (Still not sure where it scraped the URL from, but oh well).

It hit the File Browser, which currently displays a source file by opening the haxelib zip, unpacking the file, rendering it, and sending it to the client. Needless to say, with the tens (hundreds?) of thousands of files, this was causing significant strain on the server.

I've turned the preview site off for now until I fix this, either by having a faster (cached?) implementation, or by using robots.txt to block google from the file browser section.

Documentation Pages

• Creating a haxelib
• FAQ
• Installation
• Using Haxelib
• Remoting API and JSON API
• Contributing to Haxelib
• About Haxelib
• Tips and Tricks
• Menu styling
• Menu ordering
• Load top navbar menu from the actual page list, rather than hard-coding them.

Search

Do we:

1. Use a simple keyword search on title / description, or
2. Use a google web search targetting haxe.org

And then....

• Fix the search box in the nav bar
• Style the search results page
• If we are doing our own results, figure out a good balance of popularity / relevance to search on.

General CSS / templates cleanup

• In files/ , less margin under the breadcrumbs
• Add an icon to README.md
• Sort project "versions" DESC, not ASC
• On project "versions" list, add a release date column.
• On project page, show the release date somewhere.
• General margins / spacing on profile view
• Make icon in btn-primary white
• Fix search box
• Get rid of margin on code view: http://preview.lib.haxe.org/p/flixel-tools/1.0.4/files/haxelib.json
• Better code highlighting, especially for non-haxe files.
• Consider line numbering / linking, Github style.
• Check phone view and update this list as required.

Put lib.haxe live

😄 the new api.haxe is already live, would be great if we can put lib.haxe also live with this 3.2 release.

Is there anything I can do to help?

Documentation Menu

The left menu on the documentation section order does not match the drop down menu
http://preview.lib.haxe.org/documentation/using-haxelib

I'm not sure we should have a "About haxelib", we don't have much more to say here than what's already on the haxelib home page. Not sure about "Tip and tricks" also (all commands should be properly documented already).

I would put these in that order:

Getting started (would mention install, upgrade, how to open commandline on Windows :) etc)
Commands (all commands documented, nicely formated)
FAQ (where are my libs stored, contributing, reporting issues, etc)
API

As for contributing, we could have a link to Github project with an github icon in the header

File browsing to "run.n" doesn't offer a download

It just shows the directory listing again:

http://preview.lib.haxe.org/p/flixel-tools/1.0.4/files/run.n

Show dependencies on version page

It would be great to show "depends on" and "depended on by" information on the Project page.

"Depends on" we could extract from the haxelib.json.
"Depended on by" would have to be loaded from a database, with all of the dependencies added. So a bit more work, but would be useful information.

Another question: for "depended on by", do you link the dependencies with specific versions? It gets messy if you are caching version information in the DB, but it is not depending on an exact version, and then the dependency gets an update.

Popularity measurement

Regarding downloads : I think that we should not count the total number of downloads which will in general favor older libraries versus "trending ones".

A suggestion to improve that: every month, run a cron that count the number of downloads this month, then update popularity with popularity = (max(downloads-this-month,popularity) + downloads-this-month) * 0.5.

Unifying Haxe Header

The header does not use the same size / font / behavior / etc than on haxe.org (and the logo is the old one which has rendering issues :) )

Check for XSS injections in markdown files

And double check that descriptions, names etc are all safe.

API Documentation

I want to use Dox to create API documentation. A few things to consider:

• Should we use dox? Or render on each load? Advantage is that dox is awesome. Disadvantage is that when we update a template, we need to re-render every lib.
• We currently store the "haxelib.xml" document in the DB, but should we allow loading multiple xml files so we can note different platforms etc?
• Do we save the html files to disk? Database?
• Do we render dox on project upload, on first access, or on a cron job etc? If it's on upload, what do we do about all the existing projects?

Readme.md/documentation how-to

I saw on the forums questions about how this awesome readme embedding thing works. Maybe there should be a section created to explain this feature.

Use semantic versioning for ordering project versions.

This will have an effect across much of the website, and API:

• Use semver to choose the "current" (latest stable) version.
• Use semver to choose the "latest" version.
• Order all lists using semantic versioning.