Contribution Tutorial and Workflow

The best installation tutorial, best practices, and the complete workflow from A-Z for all OS’s.

If you want to contribute to the Academy as a power contributor follow this tutorial. It will save you from a lot of headaches and lost time equally. You will learn how to render a local HTML copy of the Academy and how to push your edits into the live version.

If you are an occasional contributor and you only want to add one or two lines, or fix some typos, hit the Edit on Github button in the top right corner on the Academy website, it will serve you well without bloat.

Note

General Contribution Flow

  1. Fork the particl-community/academy repository as your forked repository and clone the forked repository into your local repository.

  2. Do your changes, review them in a local live version of the Academy, commit them, and push from your local to your forked repository on Github.

  3. Create a pull request as your contribution’s integration request on the upstream particl-community/academy repository.

  4. After a manual review by the maintainers, your code gets merged.

  5. A new Academy version gets rendered and is instantly available.

  6. Congrats, you’ve created footsteps and contributed to Particl’s history.

The process of writing documentation and translations is a tedious and time-consuming task, and you will most likely get very little appreciation in doing so. I can assure you, solely the purpose is worth it, against all odds because you are Particl!

Now, let’s go dance with it!

Installation of prerequisite tools

It’s time to ensure the installation of some packages like a proper package manager, Git, Python, Sphinx, Sublime Text, and Sublime Merge.

Package Manager

It takes the hassle off you searching for installation binaries and makes it a breeze to keep them updated.

See also

  • Windows: Chocolatey is an installation package manager for Windows.

  • Mac: Brew is a package manager for Mac and sometimes Linux as well

  • Linux: There are plenty. APT, DNF, YUM, Zypper, Pacman, SNAP … to name a few.

Git

It’s the foundation protocol to handle code versions and collaboration on Github.

See also

Python

It’s the foundational language to run Sphinx.

Sphinx

Sphinx is a program that makes it easy to create intelligent documentation in reST. reStructuredText is a file format for textual data used primarily in the Python programming language community for technical documentation. reStructuredText is comparable to Markdown but with added functionality. Technically, Sphinx takes the .rst files and renders different outputs like the HTML or PDF versions of the Academy.

See also

Sublime Text

It’s a leightweight and sophisticated text editor with a myriad of extensions available. Technically, you could use any text editor, but this one is described in detail in the follow-up tutorials.

See also

Sublime Merge

It’s a sophisticated GUI for managing Git repositories. Technically, you could use any git manager, but this one is described in detail in the follow-up tutorials.

See also

Download & Install the Package Manager

  1. Open Windows Powershell (As Administrator)

  2. Paste Get-ExecutionPolicy and hit Enter. If it returns “Restricted”, paste Set-ExecutionPolicy AllSigned and hit Enter. Answer with A.

  3. Paste the code below and hit Enter

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

Download & Install Additional Packages

  1. Open Windows Powershell (As Administrator)

  2. Paste the code below and hit Enter

choco install git git-lfx gh sublimetext4 sublimemerge -y
choco install python -y
# close the powershell and open a new one; then proceed;
pip install sphinx sphinx-rtd-theme sphinx-copybutton sphinx-tabs rst2pdf

Congratulations! You have installed everything you need.

Get the Process Flying

Create a Github account, grab data from Github into your fork and local destinations, learn a bit about branches and strategies, and follow the first configuration steps to make your workflow as easy and fast as possible.

Create a Github Account

  1. Go to https://github.com/login

  2. Click on Create an account and follow through

  3. Confirm the account according to the TOS

  4. Store your Github Credentials locally

    By leaving out to store the Github login data, you’ll get prompted to enter a password every time you push something to Github. So, you want to store them –really.

    Please follow the official guides. And download here.

see also

Fork the Academy Repository

  1. Go to https://github.com/Particl-Community/academy

  2. Click on Fork

Now you have created a fork repository [username]/academy to work on.

Hint

It’s never wrong to know a bit about Remote repositories.

Clone your Forked Academy Repository Locally

  1. Open Powershell

  2. Paste the code below and hit Enter (Don’t forget to change YOUR-GH-USERNAME.)

cd %USERPROFILE%
git clone https://github.com/YOUR-GH-USERNAME/academy.git

Now you have everything you need to start tackling the Academy. By default, you are on the master branch of the Academy’s repository. Let’s configure Git, Sublime Text, and Sublime Merge.

Configure Sublime Text

  1. Open Sublime-Text

  2. Click on File > Open Folder > Navigate to and select the previously cloned academy folder.

  3. Create a new build shortcut

    1. Click on Tools > Build System > New Build System

    2. Copy and paste the code below (don’t forget to check if the folder is true in your case)

    {
"shell_cmd": "cd %USERPROFILE%\\academy & rmdir /s /q _build & make html"
}

    1. Save as buildAcademy.sublime-build

    2. Make it the default build system

      Click on Tools > Build System > buildAcademy

  4. Render Test

    If you hit CTRL + B or CMD + B on a Mac the Academy gets rendered locally as HTML within the folder _build

    In order to open it in the Internet Browser use the Folders navigation in Sublime Text’s Side Bar and unfold the _build folder. Go ahead to html/index.html, press the Right Mouse Button -> Reveal in XX -> press the Right Mouse Button on the index.html file and chose Open with or just Drag and Drop the file into your preferred Browser.

    Each time you make a change in your local copy of the Academy press CTRL + B or CMD + B on a Mac to get it rendered and refresh the page in the Browser to see the changes.

  5. Save the project

    If you save your project into a project file you are able to resume your work where you left it. It’s a handy tool.

    1. Click Project > Save project as

see also

Configure Sublime Merge

  1. Open Sublime Merge from Sublime Text on location

    Use the Folders navigation in Sublime Text’s Side Bar and press the Right Mouse Button on the academy folder and choose Open Git Repository -> Sublime Merge opens.

  2. Your forked repository is your origin

    Since you have cloned your forked repository from your account its considered as origin repository.

  3. Add the upstream repository

    Click Right Mouse Button on Remotes > select Add remote > set name to upstream and paste the URL https://github.com/Particl-Community/academy.git.

Note

Adding the upstream repository helps you later on to fetch updates and merge them into your local and origin repositories.

Sublime Merge is currently not capable to perform pull requests to upstreams. That’s why you will need to push your local commits to your fork repository and create a PR from Github’s website. There are ways to do this on the CLI but they are not covered in this tutorial.

Congratulations! You you’re almost there. Now let’s talk about workflow strategies.

Merging, Branching, and Commits

Branches in Git are snapshots of your code repository at a given state. You can switch between them and/or merge code back and forth.

With your initial cloning of your Academy as origin repository you’re by default on the master branch. As soon as you checkout (switch) into a different branch all your files get modified according to its branch status. If you switch back, you’re back on the initial code base.

Attention

Creating commits has the purpose of documentation and identification of your code contributions. So, you’re well-advised to be precise with your descriptions, and you are asked to keep related changes across multiple files into one commit but not mix up different topics in one commit. Otherwise, we will not accept your pull request (PR) if we see such a mess.

Branch: Master

Purpose

The master branch is the one where the live version of the Academy gets rendered from. As soon as changes are pushed to this branch on the upstream repository a new build process is invoked.

What you can do here

You can fix typos, add content, and create pull requests to the upstream repository.

Branch: Temp

Purpose

The temp branch is the one where you can test things back and forth. As soon as you are happy with your changes you can merge them into your master branch and push it to your origin repository and finally create a pull request from there to get it integrated into the live version aka upstream repository.

What you can do here

Anything you want.

Branch: 3.x

Purpose

It is envisioned to be on par with the advancements of the Particl Desktop software. Currently, a version named repository will be a kind of archive or snapshot for that particular version. Localized versions will emerge and look like [VersionID]-[LangID] where langID stands for your international abbreviation like for French its fr and would look like this 3.x-FR, or 3.x-DE for German.

What you can do here

Currently nothing. But in the future it might become handy if we tend to write new documentations prior to a software release.

Note

As soon as you want to change the in-depth structure, add new documents, or collaborate with multiple people at the same time it’s due to work temporarily in a different branch and once its finalized it can get merged into the master branch.

Side-note: If you work with multiple people on a branch you will work with your personal fork of the repository not on the upstream repository. You can individually grant write-access to your origin repository version of the Academy.

Creating a new branch

  1. Open Sublime Merge

  2. Click Right Mouse Button on Branches (It’s automatically under your local repository)

  3. Give it a name depending on the usecase, e.g. Testground and hit Enter.

  4. Make it the activated branch by Right Mouse Button > Checkout [Branchname].

  5. Push the locally create branch to your origin repository

    1. Be sure the correct branch in selected in the menu.

    2. Click the small dropdown arrow ▼ next to the ↑ arrow.

    3. Now choose the destination origin and click on push

You will recognize the local branch appears now under your origin branch which you can also verify on your Github page.

see also

A commit with PR by example

  1. Open Sublime Text and change your desired file

    As soon as you create a preview render with e.g. CTRL/CMD + b or you save the file, Git recognizes this change.

  2. Open Sublime Merge

    You’ll find a new unstaged file in the list of Commits.

  3. Click on Stage to qualify this particular file (and more, if there are more to stage) for the desired commit.

  4. Enter a meaningful Commit Message e.g. Changed because; Or Typo fixed; Regression fixed;.

  5. Click on Stage X files to confirm -> Your commit is written.

  6. Push this commit to your origin repository

    1. Be sure the correct branch in selected in the menu.

    2. Click the small dropdown arrow ▼ next to the ↑ arrow.

    3. Now choose the destination origin and click on push ->Your commit is pushed to Github.

  7. Create the PR

    1. Open your origin academy repository on the Github website https://github.com/[USERNAME]/academy

    2. You should see a yellow notification banner which invites you to create a PR towards the upstream repository.

    3. Leave an additional comment if you think it’s due or leave the commit message as is. It’s depending on the depth of your changes.

    4. Click on Create pull request

Congratulations! That was a wild ride. Now you have gained a lot of knowledge nobody can take away from you. May your contribution be a blessing!

FAQ

Where do I put images and videos?

Technically, they belong into the _/static/media/xxx folders. Yet, we have not started to implement supportive graphics. When the right time has come we will let you know. Then you’ll be able to add language based overlays or audio tracks.

Can I start creating new pages in my native language?

We are aiming for a cohesive file and communications structure across all languages. So, we really, really want to have the english representation as the origin of all other translated contents and not vice versa. So, if you want to create content in your language, find out if there’s already a branch named master-[LangID] where langID stands for your international abbreviation like for French its fr and would look like this master-FR, or master-DE for German. If not, create it and make a PR so that we know it has been claimed.

What do I need to consider when translating content?

  1. Try to find out if there’s already a language branch.

You can find the available branches on the upstream repository. The person who created it has a fork himself and is then a maintainer if no other person may have been denominated. Try to contact them to tackle your tasks as a team. Here you can find all the forks. If none is there, claim it.

  1. Claim langID branches like described in the previous answer.

  2. Publish your progress frequently to your fork repository.

Otherwise people willing to contribute to your language will have a hard time what to do and may face work done twice.

  1. Ensure proofreading.

In any case, it’s of utmost importance you have people at hand able to proofread your writings. Ideally, a Particl unaware person understands what you have written.

Where do I find information how reStructuredText markup works?

It has been mentioned above. But here again: Open Testpage.

How can I discuss a certain topic regarding the Academy?

Open an issue on the Upstream Academy Repository.

Can I create some PR’s for testing purposes?

You can create them, but they won’t get merged. So, behave.

Can I use a different software for editing?

Yes you can. Examples are Atom or Visual Code or really any other text editor. But you’ll need to adapt the processes yourself. So, everything in this tutorial is done the way to take you up to light-speed.