Contribution - Git tutorial (advanced)

Contribution - TutorialsHow do I submit new content to Plan ₿ Academy?

• Choose a theme for your tutorial;
• Contacted the Plan ₿ Academy team via Telegram group or [email protected] ;
• Choose your contribution tools.

• Intermediate (GitHub Desktop):

Contribution - Tutorial with GitHub Desktop (Intermediate)Complete guide to propose a tutorial on Plan ₿ Academy using GitHub Desktop

• Beginners (web interface):

Contribution - GitHub Web tutorial (beginner)Complete guide to Plan ₿ Academy tutorials with GitHub Web

Suggested tools

• Obsidian (Free, not open-source)
• Mark Text (Free, open-source)
• Zettlr (Free, open-source)
• Typora (Payware, ~€15, not open-source)

• Git (Free, open-source)
• GitHub Desktop (Free, open-source)
• Sourcetree (Free, not open-source)

• Visual Studio Code (Free, open-source)
• Sublime Text (Free with limitations, not open-source)

• Canva (Free with paid options, not open-source)
• Inkscape (Free, open-source)
• Penpot (Free, open-source)

Workflows

1 - Configure your local environment

• You must have your own fork of the Plan ₿ Academy repository on GitHub.
• Synchronize the main branch (dev) of your fork with the source repository.
• Update your local clone.

# Clone your fork (if not already done)
git clone https://github.com/<your-username>/bitcoin-educational-content.git
cd bitcoin-educational-content

# Add the source repository as a remote upstream
git remote add upstream https://github.com/PlanB-Network/bitcoin-educational-content.git

# Fetch the latest changes from the source repository
git fetch upstream

# Switch to the main 'dev' branch
git checkout dev

# Merge the changes from the source repository's 'dev' branch into your fork
git merge upstream/dev

# Push the updates to your fork on GitHub
git push origin dev

2 - Create a new branch

• Make sure you're on the dev branch.
• Create a new branch with a descriptive name (e.g. tuto-green-wallet-loic).
• Publish this branch on your online fork.

# Make sure you are on the 'dev' branch
git checkout dev

# Create a new branch with a descriptive name
git checkout -b tuto-green-wallet-loic

# Publish this branch to your online fork
git push -u origin tuto-green-wallet-loic

3 - Add the tutorial documents

• Locate the appropriate folder in the local repository (e.g. tutorials/wallet).
• Create a directory dedicated to the tutorial with a clear name (e.g. green-wallet). This folder name will also determine the URL path of the tutorial. It should be in lower case, with no special characters (except hyphens) and no spaces.
• Add the following items to this directory:
  • A subfolder named assets containing:
    • Two .webp images:
      • logo.webp: The tutorial logo (square format with background). This logo must represent the software or tool presented. If the tutorial is not specific to a tool (e.g.: a general guide to generating a mnemonic phrase), you can choose a suitable visual (e.g.: a generic icon).
      • cover.webp: A cover image displayed at the start of the tutorial.
    • A subfolder bearing the code of the tutorial's original language. For example, if the tutorial is written in English, this subfolder should be named `en'. Place all the tutorial's visuals (diagrams, images, screenshots, etc.) in this folder.
  • A tutorial.yml file containing metadata (author, tags, category, difficulty level, etc.).
  • A Markdown file containing the tutorial, named according to the language code (e.g. fr.md, en.md, etc.).

# Navigate to the appropriate folder
cd tutorials/wallet

# Create the directory dedicated to the tutorial
mkdir green-wallet
cd green-wallet

# Create the 'assets' subfolder
mkdir -p assets

# Create the subfolder for the original language code (e.g., 'en' for English)
mkdir -p assets/en

# Create the metadata file and the Markdown tutorial file (e.g., 'en.md' for English)
touch tutorial.yml en.md

4 - Fill in the YAML file

• Complete the tutorial.yml file as follows:

id: 

project_id: 

tags:
  - 
  - 
  - 

category: 

level: 

professor_id:

# Proofreading metadata

original_language:
proofreading:
  - language: 
    last_contribution_date:
    urgency:
    contributor_names:
      - 
    reward:

• id: A UUID (Universally Unique Identifier) that uniquely identifies the tutorial. You can generate it using an online tool. The only requirement is that this UUID is random to avoid conflicts with another UUID on the platform;
• project_id: The UUID of the company or organization behind the tool presented in the tutorial from the project list. For example, if you are creating a tutorial about the Green Wallet software, you can find this project_id in the following file: bitcoin-educational-content/resources/projects/blockstream/project.yml. This information is added to your tutorial's YAML file because Plan ₿ Academy maintains a database of all companies and organizations operating on Bitcoin or related projects. By adding the project_id of the entity linked to your tutorial, you create a link between the two elements;
• tags: 2 or 3 relevant keywords related to the tutorial content, exclusively chosen from the Plan ₿ Academy tag list;
• category: The sub-category corresponding to the tutorial content, according to the Plan ₿ Academy website structure (for example, for wallets: desktop, hardware, mobile, backup);
• level: The difficulty level of the tutorial, chosen from:
  • beginner
  • intermediate
  • advanced
  • expert
• professor_id: Your professor_id (UUID) as displayed on your professor profile;
• original_language: The original language of the tutorial (e.g., fr, en, etc.);
• proofreading: Information about the proofreading process. Complete the first part, as proofreading your own tutorial counts as a first validation:
  • language: Language code of the proofreading (e.g., fr, en, etc.).
  • last_contribution_date: Date of the day.
  • urgency: 1
  • contributor_names: Your GitHub ID.
  • reward: 0

Professor Plan ₿ AcademyHow do I add or modify my teacher profile on Plan ₿ Academy?

id: e84edaa9-fb65-48c1-a357-8a5f27996143

project_id: 3b2f45e6-d612-412c-95ba-cf65b49aa5b8

tags:
  - wallets
  - software
  - keys

category: mobile

level: beginner

professor_id: 6516474c-c190-41f2-b2ab-3d452ce7bdf0

# Proofreading metadata

original_language: fr
proofreading:
  - language: fr
    last_contribution_date: 2024-11-20
    urgency: 1
    contributor_names:
      - LoicPandul
    reward: 0

5 - Write the content

• Complete the Markdown file properties with:
  • The title (name).
  • A short description (description).
• Add the cover image at the top of the tutorial using Markdown syntax (replace "green" with the name of the tool shown):

![cover-green](assets/cover.webp)

• Write the tutorial content in Markdown:
  • Use well-structured headings (##), lists and paragraphs.
  • Insert visuals using Markdown syntax:

![nom-image](assets/en/001.webp)

• Place diagrams and images in the corresponding language subfolder, in /assets.

6 - Save and submit the tutorial

• Save your changes locally by creating a commit with a descriptive message.
• Push the changes to your GitHub fork.

# Create a commit with a descriptive message
git commit -m "Added green-wallet tutorial"

# Push your changes to your fork
git push origin tuto-green-wallet-loic

• Once finished, create a Pull Request (PR) on GitHub to propose the integration of your modifications.
• Add a title and a brief description to the PR. Mention the corresponding issue number in the comment.

7 - Proofreading and merging

• Wait for validation or feedback from an administrator.
• If necessary, make corrections and push new commits.

# Create a commit describing the corrections made
git commit -m "Corrections following the review of the green-wallet tutorial"

# Push the corrections to your fork
git push origin tuto-green-wallet-loic

• Once the PR has been merged, you can delete your working branch.

Content creation standards

• Formatting supported on the platform:
  • Classic Markdown: lists, links, images, quotes, bold, italics, etc.
  • LaTeX (block only, not inline): delimited by $$.
  • Inline code: Syntax with a single backtick.
  • Code blocks: Syntax with three backticks, for example:

print("Hello, Bitcoin!")

• Illustrations and diagrams:
  • All images must be in WebP format. Use this free tool to convert them if required: ImagesConverter.
  • Name visuals with 2 or 3 digits (e.g. 001.webp, 002.webp).
  • For mobile or hardware wallet tutorials, use mock-ups.
  • Use only self-created or royalty-free visuals.
  • Make sure they are relevant and of high quality.
• Graphic charter:
  • Font: IBM Plex Sans.
  • Colors Plan ₿ Academy:
    • Orange: #FF5C00
    • Black: #000000
    • White: #FFFFFF