Free Software Directory:Workflow/Entry

Please fill out the fields that are marked with a *, as they are either required, important, or helpful information. Not all information is currently shown in a completed entry, but may be used in the future, and can be 'queried', which is a type of semantic search. So it's quite fine to only fill out the information marked with a *.

Each major section below, like "1. General info", "2. GNU", etc., are tabs at the top of Form:Entry. Click on the tabs to enter information for each section. When you are done with all other tabs, don't forget to click "Save" on the last tab. (Switching tabs doesn't make the form forget the info in other tabs.)

1. General info

Name *

• (required) the name of the project. Make sure to get the capitalization and spacing right. Unnecessary capitalization is not good since MediaWiki is case-sensitive. Unnecessary spacing is a problem since it makes a url harder to type. If a project gets listed as project LOWERCASE PROJECT, we might have to move the page later, and keep the old link around, in case anyone else is linking to that page.

Short description *

• (required) Give a short description here, preferably a short sentence or less

Full description *

• (required) Describe what the project does, or what it is good for in at least two sentences. Please don't copy and paste descriptions that are longer than a sentence, since the directory puts the content under its own license. Pasting someone else's copyrighted work here is not cool.

Homepage URL *

• (required) Put the url for the project homepage here. If the project is a GNU project (see below), then the address must be in this format: http://gnu.org/software/projectname .

User level

• (optional) This describes the skill as a computer user that is required for a user to be able to use the core features of a program. This is pretty subjective, and hard to gauge, so if you don't have a sense of this, don't bother marking it.

Component programs

• (optional) This is a list of the programs that are generated when one builds the project from source. If you download qtscrobbler, then scrobble-cli is one of the component programs.

VCS checkout command

• (optional) this is the command that is used to check out the source code from version control. It's often something like: "git clone https://git.gitorious.org/spacedolphin/spacedolphin.git". Note that this isn't the address for web browsing a source code repository.

Computer languages

• (optional) this is a list of computer languages that the program is written in, like "C", "lisp", and/or "Java", or languages that the program implements, like "Scheme".

Documentation note *

• (helpful) This is a place to put links to various types and formats of free documentation. It's nice to include, since it's pretty useful for new users of complicated programs. However, it's not a good idea to put links to documentation that's not free. (Free documentation may cost money, but you can copy, change and redistribute it. You can also get the source code.)

• Links should be formatted like the following so that they are clickable and don't have line wrapping issues:

[http://some.url.com/project/documentation.html extened tutorial, or whatever]

Paid support

• (optional) Sometimes programmers or others in the community will offer support for a program, for a price. This is just one way to make money with free software, so it is good to help these people, especially since there are those who want this kind of support.

Microblog URL

• (optional) The link to a microblogging website with updates about a given project. Examples include someone's feed at: http://identi.ca

IRC help

• (optional) This is an irc channel that people can visit in order to get help using the program. The irc url format is a bit funny; #fsf at irc.freenode.net is written like this: irc://irc.freenode.net/fsf

IRC general

• (optional) An irc channel that people can use to talk about the project in general. See above for formatting of irc urls.

IRC development

• (optional) This is for listing an irc channel that is useful to discuss or listen about devlopment of the project. See above for formatting of irc urls.

Related projects

• (optional) A list of any projects that are related to the one you are entering or updating. This is useful if someone has found this project, but is really looking for something a bit different, or wants to know about one that is more stable, has a gui, uses the command line, or has more features.

Keywords

• (optional) This is a list of 'tags', or words associated with the program.

Version identifier *

• (important) Basically, this is the version number. An example is: 2.6.11 or 2.6.12-rc2 . If the version number is something like: 2.6.11-debian1, then you should probably not include the -debian1 part since that is particular to a specific distribution.

Version date *

• (important) This is the date that the project was released as the version that you entered above. One way to find this is to go to a ftp download page, or a page that lists old versions of the software, and to look at the date to the right of the source code archive. Sometimes, the release date is listed somewhere on a project page. These are the most reliable ways of finding the date.

• As a last resort, sometimes you can look at the date that is stamped on the archive that you download, but this is unreliable since that date often changes as it gets copied around or downloaded. A better bet is to look at the date of the extracted folder or files. Of course, you're interested in the last file or folder that has changed. If everything is extracted into a folder, the date on that folder should do, as long as it isn't stamped as having last changed the moment you extracted it. To see dates for the files and folders in a directory, open a terminal, cd into the directory containing the files or folder(s), and enter ls -lh.

Version status *

• (important) This marks whether the software is stable, or whether it is still being beta-tested or is alpha, etc. It's a good idea to choose and list a version of the project source code above that is 'stable', since that should have less bugs. If there is no stable version, then, beta should suffice. If the web site of the project doesn't say somewhere whether the most recent version of the software is stable or not, it is safe to assume that the latest version is stable.

Version download *

• (important) This is the download link to the source code archive for the project. The version number that you choose above must be the same as the version of the download that you point to here. Link to the tarball/zip file, not the signature or hash of the file. (So choose *.tgz, *.tar.gz, *.tar.bz2, or *.zip, etc, but not *.md5, *.md5sum, *.sha1sum, *sha256sum, *.gpg, *.gpgsig, etc.) Generally, the hash files and signatures are very tiny compared the the source archive itself, so that is another way to tell. If you want to test to see if you've picked the right one, download it and try to extract it.

Version comment

• (optional) This is a comment about the particluar version, the download file itself or another place to download the file.

Last review by *

• (important) If you have made a substantial change to an entry (which includes adding it to the directory), or if you have checked the information, then type your name or user name here.

Last review date *

• (important) If you have entered your name in the previous field, then choose today's date in the date picker. Make sure you get the month and year correct, since the calendar will display the currently entered date, and not today's date, when you first edit the field.

Submitted by *

• (important) This field should get your name or user name if you are adding a new entry to the directory. If you are only updating information, then leave it as it is, even if it is blank.

Submitted date *

• (important) If you filled out the previous field, then select today's date in the date picker.

2. GNU

Is GNU *

• (important) This marks wheter a project is part of the GNU project. A project is GNU if it is listed at gnu.org/software.

GNU package identifier *

• (important) All GNU projects have an identifer, which is basically a simplified lowercase name. Enter the name listed at gnu.org/software if it is a GNU project.

Note about the homepage *

• (important) The homepage on the previous tab (1. General info) should be listed in the format of http://gnu.org/software/projectname if the project is a GNU project.

3. Licenses *

(important) This is a very important section. Each entry must have its license(s) listed, after being checked to make sure that the project is indeed free software. The license check does not need to be thorough if the project is already part of a fully-free distribution of GNU/Linux, as they have already made some check of the software's freeness. Still, it is important to get the license(s) correct. Licenses must comply with the Free Software Directory's license requirements.

If you are listing a new version of the software, you should quickly verify that the license info is still the same for the new version.

• (important) To add another license, click the "Add another" button. If you need to list more licenses, then click the button again.

• (important) If you are updating an entry and notice that the license has changed for a newer version of the software, then click the "Remove" button to remove that particular license. Note that you will not be able to undo that removal unless you restart the editing process by clicking "Edit with form" again, or re-enter the info yourself.

License *

• (important) This is where the special license name goes. Note: the license name must be listed at Property:License, and the name must be entered exactly as it appears on that page. For example, "GPL version 2" is not correct, but "GPLv2" is. "GPLv2orlater with exception" is correct, since that is exactly how the spacing appears on Property:License.

License verified by *

• (important) This is where your name goes, since you've verified that this is the correct license, right?

License verified date *

• (important) This is today's date, if you are changing, adding or verifying this particular license. Sometimes, this field doesn't update correctly when using "Edit with form". (When you are done editing everything about the entry, save your work, take a look at the "Details" tab of the entry and see if the date for the license verification is correct. If not, then click the green "Edit" button and change the date manually.)

License note *

• (important) If there are any exceptions to a particular license, then may briefly note them here. If a given license only covers part of the code, you should say which parts of the code are covered by each given license. Also, if the user has a choice of many licenses to distribute under, then make sure that each license is listed normally, then mention each other alternative, in each "License note" fields.

4. Person Info

(optional) This is a section to fill out contact information for people who are involved in the project. You don't need to add anyone, and it's probably good not to add more than a few people in total.

• To add another person, click on the "Add another" button at the bottom.

• To remove a person, click on the "Remove" button in a person's box. Note that you will not be able to undo that removal unless you restart the editing process by clicking "Edit with form" again, or re-enter the info yourself.

Real name

• (optional) This is the name of the person you are adding

Role

• (optional) This is role of that person, such as "Maintainer", or "Contributor".

Email

• (optional) This is the person's email address. Note: you should not add someone's email address if they have not listed it in a prominent way elsewhere on the web. This is because we don't want these people's email addresses to be picked up by spam bots so they get lots of spam email. Having their address in a source code archive doesn't count as being a prominent place, but having it on their home page does count as prominent. If they write their address like: "anklebiter555 AT gnu DOT org", then include it like that, or not at all, since that format sometimes tricks spam bots.

5. Resource info

(optional) This section is for adding information about bug trackers, mailing lists, forums or repository webview pages.

• To add a resource link, click "Add another".

• To remove an existing resource link, click the "Remove" button for that resource. Note that you will not be able to undo that removal unless you restart the editing process by clicking "Edit with form" again, or re-enter the info yourself

Resource audience

• (optional) This is the type of person that this resource is aimed at. For instance, if you are listing a mailing list for developers, then this field would be "Developer". If it is a general support mailing list, then "General Support", or "User" would be appropriate.

Resource kind

• (optional) Pick the most appropriate resource kind from the dropdown list. If none are appropriate, then either consider not adding it, or filing a Bug.

Resource URL

• (optional) If you set the above fields, then please enter the link address for the resource here.

6. Categories *

(helpful) This is a place to select categories for the project, so that when people are searching for the software, they can find it by searching with the criteria they are interested in.

There is an easy way to quickly find the most relevant categories. First go down to the section marked "Use:". Look in that section for categories that match the function of the program. Then for each one of those that you mark there, look for titles on the side that match the boxes you just checked. Check any more apropriate boxes that you find like this, then repeat.

Next, do the same for the following categories: "Works-with:", "Works-with-format:", "Business:" and "Interface:". If you mark something in "Interface:", then check "Interface" in the "Use:" section. This should help you find and mark all of the categories for the program.

7. Software prerequisites

(optional) This section lists programs and/or libraries that are required to build or use the program.

• To add a requirement, click "Add another".

• To remove an existing requirement, click the "Remove" button for that requirement. Note that you will not be able to undo that removal unless you restart the editing process by clicking "Edit with form" again, or re-enter the info yourself

Prerequisite kind

• (optional) This dropdown marks whether the library or program is required to use, or build the program, etc. A weak prerequisite is one that is only required for an optional feature.

Prerequisite description

• (optional) this is the name of the library, hardware, and/or other things that are reuqired to build or use the program.

8. Etc.

(don't touch) Please leave this section alone unless you have been assigned with featuring programs. This section is for marking projects as "featured". When this happens, the most recently featured projects in the three categories below are listed on the front page (after clicking Refresh on the front page. Also refresh Featured and Featured/All.) To learn more about this task and its process, visit the [Projects] page.

Featured date

(don't touch) This is the date that the project is being listed as featured, i.e. the date that this section is being updated.

Featured source

(don't touch) This is the source of the feature. This only applies if the next field marked as "GNU Spotlight", in which case, this field should be marked exactly as "The Free Software Supporter". the FSS is the e-publication that comes out each month and contains the "GNU Spotlight".

Featured category

(don't touch) This is the category that the featured project is in. The options must be exactly "Desktop", "Development", or "GNU Spotlight".

9. Save *

This is the page that is used to save the edits and additions you have made so far. The preview button doesn't work because of the way this wiki uses SMW.

Summary *

• (important) This field should be filled out with information about all the changes you've made to this entry. If it's a new entry, you could put something like "initial commit" there.

This is a minor edit

• (optional) Mark this checkbox if the edit(s) you made were minor, such as spelling or gramatical improvements.

Watch this page

• (optional) This adds the page to your watchlist, which allows you to keep track of recent changes to pages you are interested in. (Special:Watchlist).

Are you a troll

• (optional) Trolls, please mark this field, so we can keep track of you.

Save page *

• (important) If you like the changes you've made, then go ahead and click save. This is the only way that your changes will become permanent.

Show preview

• (broken) This functionality is broken for directory entries, due to techincal details about the way that results are currently displayed using Semantic MediaWiki.

Show changes

• (beware) When you are completely done, you may want to click this button before you save. Beware! It will show you the changes to the "Entry" template in text form, and there is no way back to "Edit with form" without losing your changes, unless you save first. In this mode, you can continue editing the page in text form, but it is easy to make a syntactical error that breaks the entry (until it gets fixed by you or someone else.)

Cancel

• (beware) If you click this button, your pending changes will be discarded. If you have done a lot of work and wish to save your changes later, do not click this button.