mapping-commons/mapping-commons-cookiecutter

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: '[email protected]']
• 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
     

mapping-commons-cookiecutter's Issues

License options

Currently the only license option we have is Creative Commons (CC0). Should we provide additional license options? If yes, which ones?

The linkml-project-cookiecutter provides Apache-2, BSD-3, GPL-3, MIT, and MPL-2 as options.

@matentzn, what's your opinion?

Make it possible to use github releases if the mapping sets are too big to check in

In some cases, super large mapping sets need to be checked into version control.. It would be better if it was somehow possible instead (of adding them to mappings) to attach them to github releases. However, to do local operations like deploying a webserver with all mappings, you will still need to be able to have all mapping present in the mappings directory (sync_released_mappings?).

@ehartley Maybe this is not a super high priority right now, but its maybe not a bad idea to be a bit future proof in this regard?

Add prompts for template variables

Add human-readable prompts that will be shown to the user for each template variable. Refer to the cookiecutter docs for info on how to do this.