kudos-ink/portal

A portal for the Substrate, Polkadot and Kusama ecosystem contributors.

Kudos Portal

👉 morekudos.com

Kudos is a platform designed to streamline the process of onboarding new developers to the Polkadot ecosystem. We make it simple to browse, search and filter open GitHub contributions across the entire ecosystem, allowing aspiring contributors to find projects and tasks, which match their skill level and interests. In addition, we provide project maintainers the ability to tag open contributions with custom incentives, ranging from native tokens, NFTs, POAPs and many more. Lastly, we are working with ecosystem teams to actively curate sets of high quality, context-rich issues which aspiring contributors can begin working on immediately.

Read our full intro post on the Polkadot forum

Project Architecture

Folder structure

portal/
├── assets/             # images, fonts files, ...
├── app/                # routing purpose only, specific components/layouts
├── context/            # React context API providers/reducers
├── components/         # base components
├── data/               # data assets (JSON files) & constants
    └── constants.ts    # app constants
├── hooks/              # custom hooks
├── lib/                # lib/API overtop & connectors (e.g. fetch, notions)
├── public/             # static files/assets
├── services/           # app API interfaces
├── styles/             # global css, theming variables
├── types/              # common types
└── utils/              # utility js functions (e.g. formatters)

portal's Issues

Improvements to fix PageSpeed insights

We should improve our performance using this report as an example https://pagespeed.web.dev/analysis/https-morekudos-com/z7i9w1rr9t?&form_factor=desktop&hl=en_GB

Create "Projects" page

Overview

Create a page that list all registered projects (a.k.a teams) on Kudos in a table with 5 columns:

• Avatar: Display project logo and name.
• Categories: List project focus areas and interest types.
• Languages: Show programming languages used by the project organization.
• Number of Repositories: Indicate total project repositories under each team.
• Last Activity: Show date/time of the latest project activity.

Add a call to action banner that prompt for teams to reach out for integration opportunities.

Implementation

• Create the page layout
• Add table with the 5 previous columns
• Fetch current project data from the backend (Github page and Notion DB).
• Implement a call-to-action for team outreach.

Search bar filtering

Investigate feedback submit

Testing notifications issues

Enhanced "Interest" browsing

Overview

Enhance the user experience by introducing a feature that allows users to browse trending categories over selected time frames. This feature is designed to help users discover new projects and challenges within their areas of interest efficiently.

This is done from a dedicated a new page at "/explore/categories". The page will include a toolbar with two dropdown filters for enhanced search functionality:

• Time Range Filter: Allows users to select between week, month, or year to view trending categories.
• Category Filter: Offers a comprehensive list of categories, mirroring the current selection options.

This addition aims to facilitate users in exploring the most active projects within a specified time frame and category, with a dynamic filtering slug format for easy navigation: "Most active projects this [TIME] in [CATEGORY]."

The display will feature a results table organized into three columns:

• Project: Project avatar including: organization logo/name and repository name.
• Categories: Other associated interest categories.
• Issues Created Count: Number of issues created within the selected timeframe and category.

How

• Develop a new page at "/explore/categories" for category-based exploration
• Design a three-column table to display projects, their categories, and the count of issues created
• Implement a toolbar equipped with time range and category filters for refined searches
• Enable dynamic slug creation that reflects the selected time range and category, following the pattern "most-active-projects-this-[TIME]-in-[CATEGORY]"
• Create a backend helper function to fetch and sort projects based on the number of issues in a given category and time range, ensuring the data can be sorted in ascending/descending order for user convenience

[HOMEPAGE] Latest Issues Section

Inspired by Opensea

Analytics

Create "Project" page

Overview

Create a project page (e.g. "/project/polkadot") to offer a comprehensive overview of a team's ongoing projects, including roadmaps, similar projects, and active collaborators. This enhancement aims to facilitate community engagement and collaboration by providing a detailed snapshot of project dynamics.

Details

The proposed enhancements will include:

• A header with:

1. Avatar: Displaying the team (organization) logo alongside the team name and project title.
2. Description: A brief of the project, with the github description as a fallback option.
3. Interest Tags: For easy identification of the project's categories.
4. Project Metrics: Key statistics including number of contributors, GitHub stars, and bounty offers, if any.

• A section dedicated to showcasing the 25 most recent open issues, complemented by an "Explore More" button that directs users to a more extensive list, tagged with the project's specific slug for easy navigation.

• An "Associated Projects" segment to highlight projects connected by shared goals, contributors or partnerships.

• A "Similar Teams" section aimed at:

1. Discovery: Helping users find teams with projects in similar categories.
2. Engagement: Encouraging collaborations by identifying teams with a high degree of relevance based on category match.

Implementation Steps

• Construct a header that includes the team's avatar, a short project description (or organization description), category tags, and key project metrics.
• Add a "Milestones" section on project pages to display Kudos Milestones tracking issues, visualized as a multi-step vertical roadmap.
• Implement a table section for the latest 25 open issues with an "Explore More" feature, linked with the project-specific slug (e.g. "/explore/open-contributions-for-polkadot).
• Add an "Associated Projects" section to list connections with other projects (thru partnerships for example).
• Develop a "Similar Teams" section with:
• A backend helper to fetch and display teams in similar categories, sorted by the count of matching criteria.

Implement "Kudos Issue" label

Overview

Introduce a "kudos" label to recognize and commend exemplary contributions. This label not only celebrates outstanding work but also includes mentorship support for the contributors.

How

• Design a unique "Certified Kudos" UI badge to identify "kudos" labelled issues on the portal.
• Add a dedicated filter checkbox
• Feature Kudos issues prominently on the homepage
• Update the README with guidelines on how to achieve and utilize the "kudos" label

Support multi options selection as OR filtering for a given filter

This should work ?languages=Rust+Typescript&interests=polkadot

API pagination service

Protect us against offensive issues

Is your feature request related to a problem? Please describe.

We must prevent offensive wording in issues even if this must be handle by maintainers directly.

Describe the solution you'd like

• report action that triggers an issue resync
• pre filter issues when importing them into the DB

Describe alternatives you've considered

Add a disclaimer banner to protect against content liability.

API query ordering service

Associate a difficulty to issues

Add query filter to fetch only non assigned issues

Is your feature request related to a problem? Please describe.

Only non assigned issues should be listed.

Describe the solution you'd like

Add this filter for all queries.

[HOMEPAGE] Join the community Section

• Socials
• Schedule a call w/ Kudos Team

[HOMEPAGE] FAQ Section

Prepare/anticipate questions for Polkadot forum post

[HOMEPAGE] Trending Interest Section

Inspired by Opensea

Add backend to support tipping system

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Filters & Sort

Show more projects in the home screen

Is your feature request related to a problem? Please describe.
no

Describe the solution you'd like
Depending on the issues we have at that time, we can see in the first load of the home screen several issues from the same project (in this case, almost 50% of the issues of the table belong to Kodadot)

We should limit the number of issues for each project at least in this screen without filters.

Describe alternatives you've considered
We can accept this behavior.

Encode filter search param into a friendly SEO slug

These queries ?languages=Rust&interests=polkadot&projects=paritytech%2Fpolkadot-sdk should be encode as rust-open-contributions-in-polkadot-for-polkadot-sdk

Display issue status

• Free
• Assigned
• WIP (PR open)
• Closed

We should display free issues only on the homepage

SEO metadata & OG images

test notification

Investigate contribution sharing

UI Kit

Next UI

Redefine table's columns

Is your feature request related to a problem? Please describe.
no

Describe the solution you'd like

• We need to remove the labels in the table
• We need to show the languages, interests, projects as columns
• Those values should be buttons that can update the param's in the URL and filters the issues

Describe alternatives you've considered
no

Additional context
Similar to https://remoteok.com/

"Good first issue" checkbox

Is your feature request related to a problem? Please describe.
no

Describe the solution you'd like

• Add a "checkbox" next to the last filter and before the "clear all filters".
• When it's selected:
  • it should add a new parameter in the url
  • it should filter the issues by searching "good first issues", "c1-mentor" and also "d0-easy" labels
• when it's unselected, it should remove the parameter in the url
• it should be responsive

Describe alternatives you've considered
no

Additional context
Add any other context or screenshots about the feature request here.

Implement "Kudos Milestone" label

Overview

Introduce a "kudos-milestone" label to spotlight key tracking issues open for contributions, fostering a broader engagement with external contributors. This label aims to outline a larger vision and offer incentives upon the completion of these milestones. Each tracking issue may encompass sub-tasks to provide a structured approach to achieving these milestones.

How

• Integrate a new column in the Notion database to link each issue with a "Milestones Tracking Issue" ID
• Add a "Milestones" section on project pages to display Kudos Milestones tracking issues, visualized as a multi-step roadmap
• Create a dedicated "milestone" page
• Support dynamic slugs in the format "milestone/TITLE-for-PROJECT"
• The "milestone" page features a table for issues belonging to this specific milestone. The issues are filtered by milestone ID and the table contains columns for Status, Title, Assignee, and Date.
• Add a "Latest Kudos Milestones" section on the homepage for increased visibility

Tracking Issue for Kudos Specific Labels Integration

Overview

Kudos specific labels are designed to highlight significant contributions within the Kudos portal. This tracking issue encompasses the first batch of specific labels to be integrated: "kudos" and "kudos-milestone."

Labels

• kudos: Recognize and commend exemplary contributions with a "kudos" label, accompanied by mentorship and incentive support - #82
• kudos-milestone: Spotlight key tracking issues open for contributions with a "kudos-milestone" label to foster broader engagement - #87

[HOMEPAGE] About Kudos Section

Inspired by L2Beat

Language filter: Accuracy and values

I've tried to make the "language filter" dynamic by getting all the issues from the Notion and taking their "language repo" but I found some issues:

Accuracy

The approach of using that information isn't too accurate. Let's use the second issue from this repository as an example:

Currently, the repository has all these languages

However, there's no way to determine the language required for the issue because it lacks labels, as seen in this example.

While this method might work perfectly for repositories with only one language, it's not the most common case. This could compromise the user experience if the website displays issues not related to the selected language. Let's discuss potential solutions or adjustments to enhance accuracy and usability.

This problem doesn't affect other projects:

• OnlyDust shows repositories instead of issues.
• RemoteOK and DeWork use filters based on "pre-defined values" that are selected when the task/offer is created

Some solutions:

• show repositories instead of issues
• keep the same behaviour accepting the lack of accuracy in some cases
• use this filter only if the issue has labels
• try to find the "keyword" in the title or description

Values

To generate a dynamic list of values in the filter, currently, I need to retrieve all the issues from Notion, which requires 45 sequential requests due to the 'cursor' limitation. As illustrated in the image below, this process is slow and may not scale well in the future, potentially triggering rate limits and hindering the success of other requests.

This is slow and won't scale in the future. This can prevent other requests from being successful because it can trigger the rate limit.

Some solutions:

• use predefined values similar to RemoteOk
• take the languages from the request that gets the issues when the website loads for the first time (they won't be all, just a subset)
• save all the languages in a different backend service

Investigate project integration CTA

[HOMEPAGE] Stay in the loop (mail capture)

Kudos community alerts - newsletter -- subscribe to new features and major announcements (optional & no spam)

TODO

• Email sign up box at the top of the page (small banner)
• Bottom Section

Contributions explore table

More notifications testing

[HOMEPAGE] Top Teams Section

Inspired by Opensea

Make each issue shareable on socials with proper Metadata and OG image generation

[HOMEPAGE] Use Static contribution table with no infinite scroll

Tracking issue for tipping page

TBD

Investigate bug reporting

[HOMEPAGE] Add a "Subscribed to Next-Gen Organizations" carroussel

Describe the solution you'd like

• Implement an organization carroussel similar to Dework Bonus: make organizations clickable to redirect to the explore page: /explore/open-contributions-for-[PROJECT]
• Add an "Include your project" CTA with many also a link to a guide on how to do it

Screenshot

Improve Next caching for the homepage and Notion fetch

Consider using Tanstack SSR: https://tanstack.com/query/latest/docs/framework/react/guides/advanced-ssr

API query filtering service

Data sanitation

Is your feature request related to a problem? Please describe.
not really but it's an improvement

Describe the solution you'd like
We need to ensure that all the information displayed on the website is precise and accurate.

• We need to create a table to maintain the projects (repos) and interests (here may be a good idea https://github.com/orgs/kudos-ink/projects)
• We should get all the main repositories from polkadot-ecosystem (dapps, docs, parachains, etc)
  • https://careers.substrate.io/companies
  • https://polkadot.network/ecosystem/dapps
• We may need to update the list of repositories in the cloud functions that maintains our notion's database
• We need to check that all the languages in the filter have at least one issue
• We need to check that the repository information saved in notion has the correct languages
• Once we have all the repositories,
  • We need to redefine the "mapping" of interests
• We need to define the order of the filters' values

Show banner with message and call to action

Is your feature request related to a problem? Please describe.
no

Describe the solution you'd like

• We need to show a banner below the title to incentivize people to add their projects
• The button should open a parameterized issue or pull request
• When approved by us, the cloud functions need to take this new repository and get its issues

Describe alternatives you've considered
no

Additional context
no

Test Issue Trigger

API helpers - Notion Connectors