Archive | Tips and Tricks RSS for this section
Jan 15, 2013 

Allura feature highlight – Artifact Linking

A very cool feature in the new SourceForge (Allura) that we haven’t touted enough is artifact linking. The ability to link to other parts of the forge is available in every Allura tool, providing tight integration between the various aspects of your project.

Any forge resource (“artifact”) can be linked with surrounding square brackets, e.g. [MyPage] or [#123]. These artifact links can take several forms.

Simple Links

Most commonly, the artifact identifier can simply be surrounded with square brackets. Here are some examples:


[MyWikiPage] # Wiki - name of wiki page
[#123] # Tracker - ticket number
[r10721] # SVN - revision number
[3b9d48] # Git & Mercurial - first 6 characters of revision hash
[2012/02/my-post] # Blog - post slug, including YYYY/MM/ prefix
[a6d38f98] # Discussion Thread - thread id
[a6d38f98#42f8] # Discussion Post - thread_id#post_id

Two-part Links

To link to an artifact in a specific tool, use the form: [tool:artifact], where tool is the name of the tool as it appears in the URL. Two-part links are useful when you have two tools of the same type installed. For example, let’s say you have a ‘bugs’ tracker and a ‘features’ tracker installed, and you want to link to the first ticket in each:


[bugs:#1]
[features:#1]

Put a tracker artifact link in a commit message to link that message to the ticket in the code browser.

Three-part Links

To link to an artifact in another project, use the form: [project:tool:artifact], where ‘project’ is the name of the project as it appears in the URL. For example:

[allura:wiki:Home]

To link to an artifact in a subproject, use the form: [project/subproject:tool:artifact], where ‘subproject’ is the name of the subproject as it appears in the URL. For example:

[allura/sub:code:3b9d48]

Back-links

Any time that you link to an artifact, that artifact will automatically link back. For example, if you link from ticket #2 to ticket #3, ticket #3 will automatically have a ‘Related’ section added to it, with a link back to ticket #2. Similarly, if you link to a ticket from a wiki page, that page will have a link back to the ticket.

Inline documentation

In any editing environment (ie, if you’re editing a blog post or a wiki page) you’ll see a “Formatting Help” button that will give you a pop-up help window with formatting instructions. That includes artifact linking, as well as all other aspects of formatting in Markdown.

Oct 10, 2012 

Verifying Downloaded Files

When you download a file from SourceForge (or, indeed, from anywhere), there are often mechanisms for verifying that you’ve downloaded the right thing – ie, that nobody has tampered with the file, and that you’re getting what the developers intended for you to download.

The most common way to do this is with a file hash that gets generated with the file is created.

Verifying downloaded files

Each time a file is uploaded, we generate an MD5 hash, and a SHA1 hash of that file, so that you can quickly check whether a file has been tampered with.

In the files interface, click on the “I” information icon next to the file, and you’ll see, as in the image above, two strings labelled SHA1 and MD5. These are cryptographic strings generated from the file itself, which you can verify on your end to ensure that the file you are downloading hasn’t been tampered with somewhere between us and the mirror, or between the mirror and you.

We will also, very soon, be adding those checksum strings to the file download page itself, so that you don’t have to go out of your way to look for it.

Once you have downloaded the file, check to see that the MD5 checksum, or SHA1 checksum, of that file, matches what we list on the site. If they don’t match, notify us, then try downloading from a different mirror.

On Windows, we recommend a tool like md5deep to generate the hashes from the downloaded file. There are also browser plugins that will calculate the checksums on a file as you download it, so that you’re less likely to forget to do it yourself.

On Linux, at the command line:

$ md5sum download.tar.gz
84a3d6aa561b112058ad9aa08a352044  download.tar.gz

$ sha1sum download.tar.gz
b6133cbc973faf908f83fa950574db0fa268480c  download.tar.gz

On Mac OS X, at the terminal:

$ md5 download.tar.gz
MD5 (download.tar.gz) = 84a3d6aa561b112058ad9aa08a352044

$ shasum download.tar.gz
b6133cbc973faf908f83fa950574db0fa268480c  download.tar.gz

Again, if you discover that a checksum doesn’t match, please tell us so that we can do something about it as quickly as possible.

We also strongly encourage project admins to verify your files yourselves on various mirror servers, after you’ve uploaded them, ensuring that what’s on the server matches what you uploaded.

Sep 12, 2012 

Ticket Voting

A frequently-requested feature on the SourceForge ticket tracker is voting – the ability to let your community tell you which tickets are most important to them.

Ticket voting is here.

If your project is on the New SourceForge (if it’s not, you should upgrade now), go to Admin → Tools, and click on Options under Tickets.

Check the box next to ‘Enable voting on tickets’, and click Save.

Tickets will now contain a voting mechanism, and any authenticated user on SourceForge will be able to indicate whether a particular ticket is something that they care about.

In the list view, tickets will indicate what the current vote tally is, and you can order tickets by vote, so that you can work on what people care the most about.

You can give the feature a spin right now by going to the Allura ticket queue and telling us what you’d like for us to work on next.

Aug 10, 2012 

Getting started: Training missions

Every few days, someone asks me, how do I get started on this Open Source thing? It’s not always an easy question to answer, because the barrier to entry can be quite high. You need to know how to program. You need to find a project that interests you. And you need to navigate both the community and the technical aspects of that project.

I’ve recently been watching the OpenHatch site, with its wonderful approach to getting people involved in projects. They seem to really care about the projects, but also about the developers who are casting about looking for a place where they can be useful.

One brilliant resource on the site is the training missions. These are short exercises designed to teach you some of the basic skills required to survive in the Open Source wasteland. You do the task, and you’re evaluated by a little bit of software which is non-judgmental and won’t laugh when you make a mistake. You can do it as many times as necessary in order to get it right, and then move on to the next thing.

Over time, the list of training missions will grow, and this site will be an even more valuable resource that all of us in the Open Source community can point to, so that we don’t all have to develop this training material for ourselves.

OpenHatch also offers resources for connecting projects with developers, and I’m looking forward to seeing how this matures over time. I’m already a big fan.

While you’re there, also take a look at their project growth cookbook, which offers a lot of great ideas for getting people involved in your community.

Jun 29, 2012 

Hosted Apps migration docs: Help us out

I mentioned a few days ago that we’re retiring the Hosted Apps functionality (and, by the way, there’s some great conversation going on over on that posting), and that we were starting to work on some documentation on the process of migrating those apps to project web space.

Later that day, the Software Sustainability Institute blog posted an updated version of my migration doc, clarifying some of the things I’d explained poorly.

We really appreciate this kind of community participation in our documentation. Did you know that all of our documentation wiki pages are available for you, the community, to enhance? If you feel that there’s something we’ve explained poorly, or not at all, please feel free to update those docs. If you find that you don’t have access to update a particular doc, just ask, and we’ll set you up with the necessary permissions.

In particular, if you have experience migrating your data from a Hosted App to your web space, the whole SourceForge community could benefit from that experience.

The SourceForge platform itself is Open Source, but so is our support community, and we encourage you to participate in that process.

So, a hearty THANK YOU to Mike Jackson and the folks from the OGSA-DAI project for sharing their time and expertise with us. Now, if you’ll excuse me, I’m going to update my document.

« Newer Entries
Older Entries »