Skip to content

How to Contribute Changes

You don't need to be a developer to help improve these documents.
This guide shows you exactly how to share ideas and suggest changes, step by step.

Overview: Two Ways to Participate

Just Want to Discuss an Idea?

→ Open a GitHub Issue (no technical skills needed)
Perfect for: Sharing suggestions, asking questions, starting discussions

Want to Make the Change Yourself?

→ Edit on GitHub (easier than you think!)
Perfect for: Fixing typos, clarifying language, adding examples

→ Use VS Code (optional, for bigger changes)
Perfect for: Reorganizing sections, adding new pages, testing locally

Part 1: Starting a Discussion (GitHub Issues)

Think of this as a suggestion box or discussion forum. No technical knowledge required.

What is a GitHub Issue?

Anyone can: - Propose an idea for improvement - Ask questions about existing practices - Share what's working or not working in their circle - Discuss whether a change aligns with core principles

Step-by-Step: Opening an Issue

  1. Go to the Issues page
    Visit: practice_circle/issues

  2. Click "New issue"
    Look for the green button (top right)

GitHub issues page

  1. Give it a clear title
    Examples:
  2. "Suggestion: Shorten session length to 60 minutes"
  3. "Question: How do online circles handle silence?"

  4. "Feedback: The facilitation guide was confusing on X"

  5. Describe your idea
    Include:

  6. What problem does this solve? (e.g., "New participants find 90 minutes overwhelming")
  7. What are you suggesting? (e.g., "Offer a 60-minute beginner option")
  8. How does it align with core principles? (e.g., "Makes practice more accessible")

New issue form filled out

  1. Submit the issue
    Click the green "Submit new issue" button

  2. Join the discussion

  3. The community can comment, ask questions, discuss
  4. You'll get email notifications when someone responds
  5. If there's support, someone (maybe you!) can create a formal proposal

You're Done!

That's it. You've contributed to the community without writing a single line of code.

Part 2: Making Simple Changes Online

No software to install. Edit right in your browser.

This is perfect for: - Fixing typos or grammar - Clarifying confusing sentences - Adding examples or resources - Small formatting improvements

Step-by-Step: Editing on GitHub

  1. Fork the repository (first time only)
    Go to: practice_circle
    Click the "Fork" button in the top right corner
    This creates your own copy where you can make changes safely

Fork the repository

Note: If you've already forked it, skip this step!

  1. Find the page you want to edit
    Navigate to it on the website, or go directly to:
    https://github.com/YOUR_USERNAME/practice_circle/tree/main/docs/
    (Replace YOUR_USERNAME with your GitHub username)

  2. Click the file you want to edit
    Example: howto/organize/roles/facilitator.md

  3. Click the pencil icon (top right of the file)
    It says "Edit this file" when you hover over it

  4. Make your changes

  5. The file opens in a simple text editor
  6. You'll see the raw markdown (don't worry, it's readable!)
  7. Make your edits just like in a word processor

Markdown basics (all you need to know): 

# Heading 1
## Heading 2

**bold text**
*italic text*

- Bullet point
- Another point

[Link text](https://example.com)

GitHub web editor

  1. Preview your changes (optional)
    Click the "Preview" tab to see how it looks

  2. Commit your changes
    Scroll down to "Commit changes" section:

  3. Title: Brief description (e.g., "Fix typo in facilitator guide")
  4. Description: Explain what you changed and why
  5. Make sure "Create a new branch for this commit" is selected
  6. Click the green "Commit changes" button

Commit changes form

  1. Create a pull request
  2. On the next page, click "Create pull request"
  3. Review the summary, click "Create pull request" again
  4. Done! Your suggestion is now visible for review

What Happens Next?

  • Your "pull request" appears in the community queue
  • Others can review, comment, suggest improvements
  • Once approved (see Evolve the Circle for process), it gets merged
  • The website updates automatically!

Part 3: Using VS Code (Optional, Not Scary!)

For bigger changes or if you want to preview locally before submitting.

VS Code is a free text editor made by Microsoft. Despite being a "developer tool," it's actually quite friendly for editing markdown documents.

Why Use VS Code?

  • Edit multiple files at once
  • See the full folder structure
  • Preview markdown as you type
  • Work on changes over multiple sessions (save drafts locally)
  • Better for reorganizing or adding new pages

First-Time Setup (15 minutes)

  1. Install VS Code
    Download from: code.visualstudio.com
    (It's free and works on Windows, Mac, Linux)

  2. Install Git
    Download from: git-scm.com
    (This lets you download and sync the documents)

  3. Configure Git (first time only)
    Open VS Code's terminal (View → Terminal) and run: 

    git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Getting the Documents

  1. Fork the repository (if you haven't already)
    Go to: practice_circle
    Click the "Fork" button in the top right

  2. Clone your fork
    In VS Code:

  3. Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
  4. Type "Git: Clone"
  5. Paste: https://github.com/YOUR_USERNAME/practice_circle.git
    (Replace YOUR_USERNAME with your GitHub username)

  6. Choose a folder to save it

  7. Open the folder
    File → Open Folder → Select the practice_circle folder

  8. Create a new branch (your workspace for changes)
    In the terminal: 

    git checkout -b my-changes
    (Replace my-changes with a short description, e.g., update-facilitator-guide)

Making Changes

  1. Navigate to the file
    Use the file explorer on the left side
    Example: docs/howto/organize/roles/facilitator.md

  2. Edit the file

  3. Just type like in any text editor

  4. Install the "Markdown Preview" extension for live preview

  5. Save your work
    Ctrl+S (or Cmd+S)

Submitting Your Changes

  1. Stage your changes
    In the terminal: 

    git add .

  2. Commit your changes

    git commit -m "Brief description of what you changed"

  3. Push to your fork

    git push -u origin my-changes

  4. Create a pull request

  5. Go to your fork on GitHub: https://github.com/YOUR_USERNAME/practice_circle
  6. GitHub will show a notification about your recent push
  7. Click "Compare & pull request"
  8. Add description and submit

Or go directly to:
https://github.com/simondilhas/practice_circle/compare

That's It!

Your changes are now submitted for review, just like the web editor method.

Understanding the Review Process

After you submit changes (via either method), they go through a review process. This protects the community while enabling evolution.

See Evolve the Circle for details on: - Change tiers (small improvements vs. major changes) - How review and approval works - Experimental testing for significant changes - Timeline expectations

Key points: - Small fixes: Quick approval (1-2 days) - Bigger changes: Discussion period, testing may be needed - You'll get feedback and can revise your proposal - The process is transparent and collaborative

FAQ

Do I need permission to open an issue?

No! Anyone can open an issue. It's just a discussion.

What if I mess something up?

Nothing breaks permanently. Every change is tracked and can be reverted. Don't worry!

Can I edit without opening an issue first?

Yes for small fixes (typos, clarity). No for bigger changes—please discuss first so your work isn't wasted if the community doesn't support it.

How long does review take?

  • Typos/small fixes: 1-2 days
  • Medium changes: 1 week
  • Major changes: 2+ weeks with testing

What if my pull request gets rejected?

It's not personal! The community might: - Suggest revisions (you can update and resubmit) - Explain why it doesn't fit right now - Ask you to test it first as an experiment

This is collaborative refinement, not judgment.

I'm still intimidated. Can someone help?

Yes! Open an issue saying "I'd like to suggest X but need help with the technical part." Someone will assist you.

Remember

  • Start small: Fix a typo, clarify a sentence
  • Discussion is valuable: You don't need to make changes yourself
  • Mistakes are okay: Everything is reversible
  • Community helps: Ask questions, request assistance
  • Practice over perfection: Just like meditation practice, contributing is a practice too

You're helping shape something meaningful. Thank you.