Skip to content

Contributing to the Wiki

Below you can fiend a brief description on how to contribute for the Wiki repository.

Getting started

1. Fork the repository

First, create a fork of the repository to your personal GitHub account:

  1. Navigate to the knowledge-base repository
  2. Click the "Fork" button in the top-right corner
  3. Wait for GitHub to create the fork in your account

2. Clone Your Fork

Once you have forked the repository, clone it to your local machine:

git clone https://github.com/username/knowledge-base.git
cd knowledge-base

3. Create a new branch

Create a new branch for your changes:

git checkout -b your-branch-name

Choose a descriptive branch name related to your contribution (e.g., add-mace-tutorial, update-ase-resources).

Making changes

Adding Documentation

When adding new documentation:

  1. Create your markdown files in the appropriate location under the docs directory
  2. Use clear, concise language
  3. Include code examples, screenshots, weblinks, or diagrams where helpful

Adding Scripts

When adding scripts or code examples:

  1. Place scripts in the scripts directory or a relevant subdirectory
  2. Include reference and description of your code in the directory README.md file
  3. (Optional) Create a small documentation in the docs directory explaining how to use the script

Updating Navigation Structure

After adding new documentation, update the navigation structure in mkdocs.yml:

nav:
  - Home: index.md
  - Section X:
      - old_page.md
      - your_new_page.md  # Add your new page
  - New Section:  # Create a new section
      - new_page_section.md

Build and preview changes

Set up environment

Install the required dependencies:

pip install -r requirements.txt

Preview locally

Preview your changes locally before submitting:

mkdocs serve

This will start a local server at for example http://127.0.0.1:8000/ where you can preview the documentation.

Preview on your GitHub fork

To preview the changes on GitHub Pages from your fork:

  1. Go to your forked repository on GitHub
  2. Click on "Settings"
  3. Navigate to the "Pages" section in the sidebar
  4. Under "Source", select "Deploy from Branch"
  5. Under "Branch", select "gh-pages" and "/root"

The documentation site will be built automatically when you push changes to your fork.

Submitting your contribution

Commit and Push Changes

Once you're satisfied with your changes:

git add .
git commit -m "Add a clear description of the changes"
git push origin branch-name

Create a pull request

  1. Navigate to your fork on GitHub
  2. Click "Pull Request"
  3. Select the branch containing your changes
  4. Add a clear title and description of your changes
  5. Important: Assign at least one reviewer to examine your changes
  6. Click "Create Pull Request"

Review process

  1. Wait for feedback from the assigned reviewers
  2. Make any requested changes to your branch
  3. Push the changes to automatically update the pull request
  4. Once approved, a maintainer will merge your contribution

Best Practices

  • Keep changes focused: Each pull request should address a single concern
  • Test thoroughly: Ensure all links work and documentation renders correctly
  • Follow existing patterns: Maintain consistency with the current structure
  • Request reviews: Always request at least one review before merging
  • Communicate: Use clear commit messages and PR descriptions