Discussion and Contributing

Contributing to this wiki

To add to this wiki either:

  1. Add an ‘issue’ explaining your suggestion to the Issue Tracker of the site’s repository on GitHub. Someone else can then pick up the suggestion and incorporate it into the site. (very simple to do, good for anyone not yet comfortable with GitHub or Sphinx)
  2. Edit the site yourself by submitting a pull-request (requires knowledge of GitHub and Sphinx but significantly reduces the workload for the Core Team)

Editing the site

This site is built using Sphinx, a Python package that creates static websites such as wikis or project documentation. The site is made up of a collection of rst and markdown text files with Sphinx turning the text files into a full website.

The site’s code is version controlled using Git and hosted on GitHub.

A Conda virtual environment is used manage the build environment and reduce the chance of build errors.

This site follows the standard steps for contributing to a GitHub based open-source project.

First time setup

  1. Fork the site’s repository to your personal GitHub account.

  2. Clone your fork to your local machine:

    cd desired_folder # change directory to the location where you will keep the project
    # where user_name is your github username
    git clone git@github.com:user_name/open-actuarial-site.git # if using ssh or
    git clone https://github.com/user_name/open-actuarial-site.git # if using https
  3. Add the main project as upstream (allows you to pull in changes made by others):

    # add upstream (location of main repository)
    git remote add upstream  git@github.com:open-actuarial/open-actuarial-site.git # if using ssh
    git remote add upstream https://github.com/open-actuarial/open-actuarial-site.git # if using https
  4. Move into project directory:

    cd OpenActuarialSite # move into the site's working directory
  5. Set up the environment:

    pip install conda # if you do not have conda installed already (you will do if you have installed Anaconda)
    conda env create -f wiki_env.yml # creates a virtual environment using the yml file for the list of packages
    # start the virtual environment
    activate wiki # for windows
    source activate wiki # for MacOS or Linux

Making changes

  1. Fetch upstream updates from main GitHub repository (in case anyone else has made changes since you last worked on the project):

    git pull upstream master
  2. Create a new branch for your suggestion:

    git branch branch_name # where branch_name is the name of the feature or bug
  3. Make the changes by adding new pages to the wiki (as rst or md files), editing existing ones or a combination of both

  4. Test that the change has the desired effect by rebuilding the wiki using Make HTML:

    make html # from windows CMD not Git Bash
  5. Commit the change to the feature branch:

    git add file_name # to stage a change to a single file, or
    git add . # if staging changes to all files
    git commit -m "commit_message"
  6. Push the changes to your forked GitHub repository:

    git pull upstream master # (to check for changes by others)
    git push origin branch_name
  7. Submit a pull request on main repository

  8. The change will be reviewed by the Core Team - if revisions are requested further commits may be required

  9. Pull request is accepted or rejected

If using two-factor authentication (2FA)

On windows, GitHub for Windows makes it a lot easier to use 2FA. If using the command line then you will use ssh. See Settings on your GitHub account to set up ssh keys.

Once ssh keys are set up:

  1. Test ssh connection (from GitHub articles):

    ssh -T git@github.com
    # Attempts to ssh to GitHub
  2. Launch ssh agent:

    eval $(ssh-agent -s)
  3. Add private key (if not already added):

    ssh-add ~/.ssh/id_rsa
    # assumes key is already set up