Skip to content

mapping-commons/mapping-commons-cookiecutter

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

28 Commits
 
 
 
 
 
 
 
 

Repository files navigation

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
      

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published