Presenting a repository so people actually look at it

The name

Clear, not clever. expense-tracker beats moneymaker3000. The reader sees a list of ten repositories and decides from the names which to open.

The name should say what it is. If it can't, add a short description in the settings — it shows next to the listing.

What to pin

Profiles let you pin repositories to the top. Pin your best three. Everything else drops out of the way.

It's the fastest improvement available: five minutes, and the first impression changes completely.

Structure

No clutter in the root. The usual arrangement: sources in one folder, configuration separately, documentation separately.

And check the repository doesn't contain:

• dependency folders — those aren't stored, that's what the manifest is for;
• files with passwords or keys — those belong in environment variables;
• editor and system junk;
• commented-out code kept "just in case".

The last is especially visible: commented-out code reads as "this person isn't sure what they're doing".

Commit history

It says as much about you as the code. What's visible from outside:

• whether you worked steadily or assembled it in one night;
• whether you can split changes into meaningful pieces;
• whether you write comprehensible messages.

A good message explains what was done: "add amount validation to the expense form". A bad one says nothing: fix, update, changes.

Don't rewrite old history. Starting to do it properly from now on is enough.

Details people notice

• A licence. One line, but it shows you know why it's there.
• An example configuration file. An empty template listing the required variables makes running it far easier.
• A passing build. If automated checks are set up and green, that's a plus without a word said.
• Replies in discussions. If someone asked a question and you answered, it's visible and reads well.

On shared repositories

In a team repository it's visible who did how much: the history is open. That works in your favour if you genuinely worked, and against you if you were merely listed.

Hence a simple conclusion: in a team project it's better to take less and do it yourself than to take a lot and hand it out. The history records the former.