Recent Changes

2017-09-22
2017-09-19
2017-09-06
2017-09-03
2017-09-02

File Release Guide

By using OSDN's file release function, you can distribute softwares created by your project.

File release related terms

OSDN's file release system is managed in a layered structure, as it's shown below. First, we'll talk about each of these terms.

Package
  |
  +---Release
  |   :
  |   :
  +---Release
       |
       +---File
       |   :
       |   :
       +---File

Package

Package is the largest unit for file release, and often, it is given the name of the software. Because there are many projects giving the same name for the software and project, as default, we provide each project with a package that has the project's UNIX name. (You can certainly change the name if you want to.)

A project can have multiple packages. For example, let's say there's a project called “foo” which develops not only a software called “foo”, but also a software called “bar”. In that case, it would be convenient to create packages called “foo” and “bar”.

Release

Each package can have multiple releases.

Release comprises the followings.

  • File (or files)
  • Release Notes (can be written in multiple languages)
  • Change Log (can be written in multiple languages)

In short, release is a collection of all the related files that are to be actually distributed.

For example, let's say you want to release version 0.1 for a program called foo. In that case, you will create release “0.1” under the package “foo”. Then, You will upload the file for the actual program, foo version 0.1. You would also want to write a release notes (about things like “The first release” or “Still the alpha version”), and add to the change log with the things have been changed since the last release.

The releases that have been created will be displayed in a list which allows general users to download from there.

How to release

Conducting a file release is limited to the users with permission, such as project admins and release admins.

The procedure for file release is as follows.

  1. Create a package.
  2. Create a release. (File upload)

1. Create a package

Once a project has been registered, a package will be automatically created, and it will be named the same as the project's UNIX name. If you're okay with the name, then you don't have to create a new package. You may move on to the next step.

To create a Package, find "Add Package" button from the release list or the admin page for the downloads, and click. Enter the package name, then select the open/closed status. Generally, it should be fine with "open". (We'll elaborate on the status later in the chapter.)

2 Create a release

Once you've created a package, you can add releases to that package. Find the “Add Release” button from the release list or the admin page for the downloads, and click.

For a release, you can set up the following items of information.

  • Release name
  • Open/closed status
  • Release notes
  • ChangeLog
  • Files included in the release

Release notes and ChangeLog can be written in multiple languages.

For each release, you can add multiple files. And for each of those files, you can also set up the open range.

From browsers (that support uploading multiple files), you can upload multiple files simultaneously.

You could also use FTP for uploading files. When using FTP for uploads, make sure the switch for FTP uploading is turned on. Information regarding FTP uploading will be displayed.

For each file upload, the file size is limited to 4.7GB.

For each release, you can attach “release note” and “change log” documents. To attach documents, choose the methods you like from the following options.

  • Use wiki format for the description
    • From the entering form on the release's edit page, enter using wiki format
    • Can be described in different languages separately
  • Display the contents of a file
    • Can display the content of a file whose file name is recognized by the system as release note/change log file.
    • File names that are recognized as release note are "readme", "release", and "releasenote". (Does not distinguish between capital and small letters. )
    • File names that are recognized as change log are "changes" and "changelog". (Does not distinguish between capital and small letters. )
    • Support file formats such as text (files without extension or with .txt filename extension will be treated as text files), html (files with .htm or .html filename extension will be treated as html), and markdown (files with .md filename extension will be treated as markdown).
    • You can display files written in different languages separately by assigning a language after the filename (and before the filename extension) along with a hyphen. (For example, README-ja.text will be treated as a release note written in Japanese.)
    • Support UTF-8 character encoding (Files that are written in other code may generate character corruption).
    • Regarding html, some of the tags will be ignored.
    • Even if the filename matches, it will not be shown if it is not a text file.
    • Documents over 30k bytes or bigger will not be shown.
    • The public/hidden status of the file has to be set to “public”. (Files that are set to hidden or private status will not have the contents used for display.)

When the system recognizes files, from among the uploaded files, that match the conditions, the names of those files will appear on editing UI for the release. To show the contents of the files, select the files from there (Please note, it will not be updated without your consent to apply). In addition, please note that after the applying process, all the document information that was entered in the entering form will be deleted.

About Public/Private Status

For each package/release/file, you can set up "open range" individually.

  • Public: Anyone can access (and this is generally selected.)
  • Hidden: Will not be displayed in the list (except when viewed by the project admin/file release admin). However, anyone with the knowledge of the URL to access can access directly. This is what would want, for example, when you want the project members to check for any mistakes before making the file public.
  • Private: Only project admin/file release admin can view. (Even with the knowledge of the URL, anyone without the permission can not view.)

You can set up public/private status for each package/release/file, but an actual status will be affected by its higher rank. (If you're talking about a release, then it will be influenced by the package, and if it's a file that you're talking about, then it will be influenced by the release and package that includes that file.)

For example, let's say the status for a release is set to public, but the package that includes that release is set to hidden, then that release will not appear in the list.

Preferred Download

You can also set up preferred download to make a file displayed with priority in places like file release list, project top page, and so on. For example, by specifying a file to be the stable version, you can make it appear in a way that stands out among other files, and that way, you can get the users to download that file with priority.

You can specify one preferred download for each file type.

System Requirements

You can edit the system requirement in which you can write about the operation conditions of the program you have released. For each project as a whole, you can edit the system requirements (in multiple languages).

Release File URL Formats

URLs that specify packages, releases, and release files will be expressed as below.

  • Package URL: https://osdn.net/projects/(Project Name)/releases/(Package id)
  • Release URL: https://osdn.net/projects/(Project Name)/releases/(Release id)
  • Release File URL: https://osdn.net/projects/(Project Name)/downloads/(Release id)/(File Name)/

When leading users from project web to download page, they will be notified by a release or with release-file URL format shown above. There are some URL formats that specify a mirror server, but historically speaking those URLs don't have the permanence, so you are recommended to hold back on using them. By the way, package id and release id are just a line of numbers, and that may cause inconvenience when a project is trying to notify a download URL. For that reason, there's a simplified URL format as shown below that specifies a package/release/release file.

  • Simplified Package URL: https://osdn.net/pkg/(Project Name)/(Package Name)
  • Simplified Release URL: https://osdn.net/rel/(Project Name)/(Release Name)
  • Simplifed Release URL (specified Package name): https://osdn.net/rel/(Project Name)/(Package Name)/(Release Name)
  • Simplified Release-File URL: https://osdn.net/dl/(Project Name)/(File Name)

At times, files with a same name could coexist in a project, and in such cases, when that package/release/file name is using the above format, this will become an URL that designates the newer one.

Also regarding releases, there may be cases where multiple packages share a same name. For example let's say a project have package A and B and both contain release 1.0. On such case, by specifying the package name, you can clarify which release for which package.

Given TeraTerm 4.90 as an example, you can use URLs like the ones below for public announcements. Use them accordingly.

Direct Download

Currently, when a release-file URL is accessed from wget, curl, libwww-perl, or PowerShell, downloading of the file will begin right away without having to go via html page.

Upload a File Release without Using Web UI

You can use OSDN's REST API to upload and edit file releases. We are also equipped with command line tools that were implemented through the use of this API. By using the command-line tools, you can reflect file tree of the local side to the release-file tree of the OSDN side, easily with a simple command.