Managing Repository Topics (Hashtags)

# Managing Repository Topics in AllSpice

AllSpice supports Topics, a feature based on Gitea’s “Manage Topics” functionality. These are short keyword labels you can attach to your repository to improve discoverability and organization. Think of them like “hashtags” for your repository. Note that these Topics are different from Git tags, which are references to specific commits.

Why Use Topics?

• Discoverability: Repositories with topics are easier to find through search or in a list of tagged projects.
• Organization: Topics let you categorize or group your projects around a particular technology, feature, or domain.
• Collaboration: Collaborators can quickly identify the purpose or scope of a repository by checking its topics.

Prerequisites

1. Repository Ownership or Write Access
   You must have the appropriate permissions (owner, admin, or at least write access) to add or manage topics in a repository.

2. AllSpice Instance
   You should have access to a running AllSpice instance (self-hosted or otherwise) where you can log in.

How to Add Topics to Your Repository

1. Log In
   Go to your AllSpice instance and sign in with your account.

2. Navigate to Your Repository
   From your user dashboard or the repositories list, select the repository to which you want to add topics.

3. Click Manage Topics
   Click "Manage Topics" below the "<> Files" Tab in the upper left side of the tab.

4. Type name of Topic
   Type the name of your topic, like "prototype"

5. Select the topic from the drop-down list
   After you have typed the name, you must select the name from the drop-down list. If you do not select the item from the list below, you cannot save the topic.

6. Click Save
   Click the Save button to save the topic.

How to Remove or Edit Topics

1. Open the “Manage Topics” Section
   Return to the same Manage Topics interface.

2. Remove Topics

   • Click the “X” next to a topic or delete it in the text field.
   • Confirm the removal if prompted.

3. Edit Topics

   • Remove a topic and add a new one in the text input box.
   • Save your changes when done.

Tips & Best Practices

• Keep Topics Relevant
  Use topics that accurately describe the project’s domain, programming language, or major function (e.g., plugin, documentation, hardware).

• Use Clear, Concise Words
  Keep them short and use consistent formatting or casing. This helps others discover and recognize your project quickly.

• Avoid Overloading
  While there’s typically no strict limit, using too many irrelevant topics can clutter your repository’s profile. Choose the most relevant tags for clarity.

• Use Common Topics
  If you’re tagging programming languages, frameworks, or popular tools, try to use standard names or widely recognized acronyms so others can find your repository more easily.

Differences Between Topics and Git Tags

• Purpose:

  • Topics: High-level categorization for search and discovery across repositories.
  • Git Tags: References to specific points (commits) in a repository’s history, often used for marking release versions (e.g., v1.0.0).

• Visibility:

  • Topics appear on the repository’s main page as labels, used for browsing and filtering.
  • Git Tags are version control objects you can list via Git commands or within the repository’s code management tools.

• Usage:

  • Topics are not tied to a repository’s code history or commit structure and can be added or removed at any time to refine categorization.
  • Git Tags are typically created (and sometimes signed) to mark important commits and are not used for classifying the repository in a broader sense.

Searching by Topic

• To explore repositories by topic, you can use the search bar within AllSpice and type a topic.
• You can click on a topic from a repository’s main page to see other repositories that use the same topic.

Further Assistance

• Check your AllSpice instance’s documentation or help resources for additional details on the user interface and permissions related to topics.
• If you run into issues (e.g., you don’t see the “Manage Topics” option, or topics aren’t saving), ensure you have the correct access permissions or contact your AllSpice administrator.

Happy tagging!