Getting started

Step 1: Create a virtual environment

First, create a virtual environment of your choice (anaconda, venv, pyenv, poetry etc.). If you need assistance with virtual environments, here's a guide to help you setup pyenv and use poetry with it.

Step 2: Install cruft in your virtual environment

Install the cruft package. Cruft enables keeping projects up-to-date with future updates made to this original template.

pip install cruft

Step 3: Use cruft to create your Mapping Commons project

In your virtual environment, create a project using the mapping-commons-cookiecutter template.

cruft create https://github.com/mapping-commons/mapping-commons-cookiecutter

This kickstarts an interactive session where you declare the following:

• project_name: Name of the project. [defaults to: my-commons-name]
• project_description: Description of the project [defaults to: 'This is the project description.']
• github_or_gitlab: Choose from [1]: github, [2]: gitlab
• git_org: Name of the github (or gitlab) org the project belongs to. [defaults to: my-org]
• full_name: Name of the author [defaults to: 'My Name']
• email: Author's email [defaults to: 'my-name@my-org.org']
• license: Choose from [1]: Yes, [2]: No [TEST OPTION FOR NOW]
• inverse_mappings: Do you want to create inverse mappings where the subject_id and object_id are switched? Choose from [1]: No, [2]: Yes

Step 4: Create a GitHub/GitLab project

GitHub

1. Go to [https://github.com/new] and follow the instructions, being sure to NOT add a README or .gitignore file (this cookiecutter template will take care of this for you).

2. In a terminal, change to the folder your generated project is in and initialize git for the project.

   cd my-commons-name
   git init
   git add .
   git commit -m 'Initial commit' -a

3. Follow the instructions to 'add the remote to your local git repository'.

   git remote add origin https://github.com/my-user-or-organization/my-commons-name.git
   git branch -M main
   git push -u origin main

GitLab

1. Go to [https://gitlab.com/projects/new#blank_project] and follow the instructions, being sure to NOT add a README file (this cookiecutter template will take care of this for you).

2. In a terminal, change to the folder your generated project is in and follow the instructions to 'push an existing folder'.

   cd my-commons-name
   git init --initial-branch=main
   git remote add origin https://gitlab.com/my-user-or-organization/my-commons-name.git
   git add .
   git commit -m 'Initial commit'
   git push -set-upstream origin main

What does this do?

The following files and directories are autogenerated in the project:

TODO

This section is under development. If you have questions about this in the meantime, reach out on https://github.com/mapping-commons/mapping-commons-cookiecutter/issues.

Future updates to the project's boilerplate code

To keep your project in-sync with the latest version of the template, you can first check if there is a mismatch between the project's boilerplate code and the template and then update your project if there is a difference. This can be done either in the virtual environment where you installed cruft or by using the odk docker container.

Check if your project is up-to-date with the template

This indicates if there is a difference between the current project's boilerplate code and the latest version of the project template.

In the virtual environment:

cruft check

Using the ODK:

sh odk.sh make cruft-check

If the project is up-to-date with the template:

SUCCESS: Good work! Project's cruft is up to date and as clean as possible :).

Otherwise, it will indicate that the project's boilerplate code is not up-to-date by the following:

FAILURE: Project's cruft is out of date! Run `cruft update` to clean this mess up.

If you want to view the difference before applying the update, you can run cruft diff (in the virtual environment) or sh odk.sh make cruft-diff (using the ODK).

Update your project

This updates the project's boilerplate code to the latest version of the template.

In the virtual environment:

cruft update

Using the ODK:

sh odk.sh make update-repo

If you want to change the values of the template variables in addition to updating the template or if your project is already up-to-date and you just want to change the variable values:

1. Edit the values in config/project-cruft.json. Note: Do NOT edit the .cruft.json file.
2. Run:
   • In the virtual environment

     cruft update --variables-to-update-file config/project-cruft.json
     

   • Using the ODK

     sh odk.sh make update-variables