Skip to content

docs: improve contributor onboarding and cross-platform setup#46

Open
adarsh-7-satyam wants to merge 1 commit into
chaoss:mainfrom
adarsh-7-satyam:improve-onboarding-and-setup
Open

docs: improve contributor onboarding and cross-platform setup#46
adarsh-7-satyam wants to merge 1 commit into
chaoss:mainfrom
adarsh-7-satyam:improve-onboarding-and-setup

Conversation

@adarsh-7-satyam
Copy link
Copy Markdown

Summary

This PR focuses on improving contributor onboarding and cross-platform local setup for the UNSDG-classifier-tool project.

While exploring the repository and setting up the project locally, I noticed that the current onboarding flow can be slightly challenging for first-time contributors, especially contributors using Windows environments. The existing setup instructions were primarily Linux/macOS-oriented and did not fully cover common setup issues, environment configuration guidance, or troubleshooting steps.

Improving the onboarding experience can help reduce setup friction and make local development more accessible for contributors across different environments.


Problems Identified

1. Cross-platform setup gaps

The setup instructions mainly used Linux/macOS commands such as:

source ./myvenv/bin/activate

However, Windows contributors typically use PowerShell or CMD, where the activation commands are different.

This could create confusion for contributors trying to run the project locally on Windows.


2. Missing contributor-focused setup documentation

The repository had setup instructions in the README, but there was no dedicated development/onboarding guide covering:

  • local development workflow,
  • troubleshooting,
  • environment setup,
  • startup order,
  • first-time setup expectations.

3. Missing environment variable template

The repository did not include a .env.example file, making it difficult for contributors to understand:

  • which environment variables may be used,
  • where configuration files should be placed,
  • and how optional API tokens can be configured.

4. Setup flow clarity

There were a few areas where onboarding clarity could be improved:

  • repository clone path consistency,
  • startup instructions,
  • version verification commands,
  • backend/frontend navigation flow.

Changes Made

Added DEVELOPMENT.md

Created a dedicated development and onboarding guide containing:

  • separate Linux/macOS setup instructions,
  • separate Windows PowerShell setup instructions,
  • virtual environment activation commands,
  • frontend/backend setup flow,
  • startup instructions,
  • troubleshooting guidance for common Windows issues,
  • notes about first-time AI model downloads.

Improved README setup section

Updated the README to:

  • improve setup clarity,
  • standardize repository naming/path references,
  • simplify the Quick Start flow,
  • link contributors to the dedicated DEVELOPMENT.md guide.

Added backend/.env.example

Added an example environment configuration template to help contributors understand optional configuration variables such as:

  • GITHUB_TOKEN
  • OSDG_TOKEN

The template intentionally avoids real secrets and clearly documents that the variables are optional.


Added troubleshooting guidance

Documented common onboarding issues including:

  • PowerShell execution policy problems,
  • Python PATH issues,
  • environment activation problems,
  • first-time dependency/model download expectations.

Impact

These improvements aim to:

  • reduce onboarding friction for new contributors,
  • improve Windows compatibility guidance,
  • make local setup easier to follow,
  • and provide a cleaner development workflow for future contributors.

Signed-off-by: Adarsh Satyam <adarsh5.satyam@gmail.com>
@adarsh-7-satyam adarsh-7-satyam force-pushed the improve-onboarding-and-setup branch from a42a7f9 to a4767cb Compare May 9, 2026 12:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant