Skip to content

Commit 6e4b54f

Browse files
authored
Cookiecutter directions for new project generation (#277)
Resolves [#ISSUE, #ISSUE] - [x] `docs/` have been added/updated if necessary Fixes #273
1 parent 78d6a3c commit 6e4b54f

File tree

1 file changed

+66
-0
lines changed

1 file changed

+66
-0
lines changed

src/docs/create-mapping-commons.md

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Getting started
2+
3+
- First, create a virtual environment of your choice (anaconda, venv, pyenv, poetry etc.). If you need assistance with virtual environments, [here's a guide](https://berkeleybop.github.io/best_practice/python_environments) to help you setup pyenv and use poetry with it.
4+
- Install the [cruft](https://github.com/cruft/cruft) package. Cruft enables keeping projects up-to-date with future updates made to this original template.
5+
6+
```
7+
pip install cruft
8+
```
9+
- Create a project using the [mapping-commons-cookiecutter](https://github.com/mapping-commons/mapping-commons-cookiecutter) template.
10+
```
11+
cruft create https://github.com/mapping-commons/mapping-commons-cookiecutter
12+
```
13+
14+
This kickstarts an interactive session where you declare the following:
15+
- `project_name`: Name of the project. [defaults to: my-commons-name]
16+
- `github_org`: Name of the github org the project belongs to. [defaults to: my-org]
17+
- `project_description`: Description of the project [defaults to: 'This is the project description.']
18+
- `full_name`: Name of the author [defaults to: 'My Name']
19+
- `email`: Author's email [defaults to: '[email protected]']
20+
- `yo`: Choose from [1]: Yes, [2]: No [**TEST OPTION FOR NOW**]
21+
- `license`: Choose from [1]: Yes, [2]: No [**TEST OPTION FOR NOW**]
22+
23+
# What does this do?
24+
25+
The following files and directories are autogenerated in the project:
26+
# TODO
27+
28+
# Version control
29+
## GitHub
30+
31+
1. Go to [https://github.com/new] and follow the instructions, being sure to
32+
NOT add a README or .gitignore file (this cookiecutter template will take
33+
care of this for you)
34+
35+
2. Add the remote to your local git repository
36+
37+
```bash
38+
git remote add origin https://github.com/my-user-or-organization/my-commons-name.git
39+
git branch -M main
40+
git push -u origin main
41+
```
42+
43+
## GitLab
44+
45+
### TODO
46+
47+
# Future updates to the project's boilerplate code
48+
49+
In order to be up-to-date with the template, first check if there is a mismatch between the project's boilerplate code and the template by running:
50+
```
51+
cruft check
52+
```
53+
54+
This indicates if there is a difference between the current project's boilerplate code and the latest version of the project template. If the project is up-to-date with the template:
55+
```
56+
SUCCESS: Good work! Project's cruft is up to date and as clean as possible :).
57+
```
58+
59+
Otherwise, it will indicate that the project's boilerplate code is not up-to-date by the following:
60+
```
61+
FAILURE: Project's cruft is out of date! Run `cruft update` to clean this mess up.
62+
```
63+
64+
For viewing the difference, run `cruft diff`. This shows the difference between the project's boilerplate code and the template's latest version.
65+
66+
After running `cruft update`, the project's boilerplate code will be updated to the latest version of the template.

0 commit comments

Comments
 (0)