You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
First of all, thank you for taking the time to contribute! 🎉
4
+
5
+
When contributing to [this project](https://github.com/engineervix/cookiecutter-wagtail-vix), please first create an [issue](https://github.com/engineervix/cookiecutter-wagtail-vix/issues) to discuss the change you wish to make before making a change.
3. Check out a new branch and add your modification.
12
+
4. Write tests, and ensure that they pass.
13
+
5. Update `README.md` for your changes. Please make sure that the Table of Contents is up to date. [DocToc](https://github.com/thlorenz/doctoc) makes this pretty easy, as you simply run `doctoc README.md` (You can install it globally on your system via `npm install -g doctoc`).
14
+
6. Commit your changes via `cz commit`, following the prompts to appropriately categorize your commit.
15
+
7. Send a [pull request](https://github.com/engineervix/cookiecutter-wagtail-vix/pulls) 🙏
-[Testing and Code Quality](#testing-and-code-quality)
29
47
-[CI/CD / Production](#cicd--production)
30
48
-[Project Features](#project-features)
31
49
-[Misc](#misc)
32
50
-[Done](#done)
33
51
-[Deprecated](#deprecated)
34
-
-[📋 Reference](#-reference)
52
+
-[Contributing 🤝](#contributing-)
53
+
-[Show your support](#show-your-support)
54
+
-[Credits 👏](#credits-)
55
+
-[Reference 📋](#reference-)
56
+
-[Author](#author)
57
+
-[License 📝](#license-)
35
58
36
59
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
37
60
38
-
## What is this ❓
39
-
40
-
This is my take on creating a reusable (and heavily opinionated) [Wagtail 2.1x](https://docs.wagtail.io/en/stable/releases/2.12.html) / [Django 3.x](https://docs.djangoproject.com/en/3.1/releases/) project skeleton using [cookiecutter](https://github.com/audreyr/cookiecutter).
41
-
42
-
This cookiecutter template is mostly a reflection of my personal preferences. It does, however, try to employ "best practices", for example, the [12-factor-app](https://12factor.net/) and [Daniel Greenfeld’s **Cookiecutter Django** framework](https://github.com/pydanny/cookiecutter-django). I also got a lot of ideas from some excellent wagtail-based projects, primarily [bvspca](https://github.com/nfletton/bvspca) and [bakerydemo](https://github.com/wagtail/bakerydemo).
61
+
## Features ✨
43
62
44
-
Notwithstanding the foregoing, it is nowhere near perfect, and thus remains a work in progress. Contributions and suggestions for improvement are welcome.
45
-
46
-
## :tada: Features
47
-
48
-
- A starting point for a CMS-based website project, with so many batteries included:
63
+
- An opinionated starting point for a CMS-based website project, with so many batteries included:
49
64
- a homepage and "About" section, which includes addition of key personnel (with position, bio, social profiles, etc.)
50
65
- a minimal functional blog with simplified categories and tags,
51
66
- a contact page with contact form and location map. Includes SMS support powered by [Vonage](https://www.vonage.com/) (formerly _Nexmo_)
@@ -71,13 +86,16 @@ Notwithstanding the foregoing, it is nowhere near perfect, and thus remains a wo
- Documentation on setting up the project (This README and the generated project's README!)
73
88
- A ready to use VSCode configuration, just update the path to your python executable in the generated `.vscode/settings.json`.
74
-
- ... and so much more ...
89
+
- The project comes with three Continuous Integration configurations (Simply choose one of the three and delete the others. If you don't like any of these three, feel free to use other options such as [Travis CI](https://travis-ci.org/), [Jenkins](https://jenkins.io/), etc.):
- A [\*nix](https://en.wikipedia.org/wiki/Unix-like) environment. My preference is Ubuntu (LTS version such as [18.04](https://wiki.ubuntu.com/BionicBeaver/ReleaseNotes))
98
+
- A [\*nix](https://en.wikipedia.org/wiki/Unix-like) environment is highly recommended. Although you can possibly develop on Windows too (if you do, and you're using Powershell or CMD, you'll probably have to adapt some commands to suit a Windows Environment, because these docs assume you're running in a \*nix environment)
81
99
-[Node.js](https://nodejs.org/) with the following packages installed **globally**:
@@ -91,78 +109,48 @@ Notwithstanding the foregoing, it is nowhere near perfect, and thus remains a wo
91
109
-[Python3](https://www.python.org/) (3.6 and above) with [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/), [pyenv](https://github.com/pyenv/pyenv) and [pip-tools](https://github.com/jazzband/pip-tools).
92
110
- The project uses the [PostgreSQL Backend](https://docs.wagtail.io/en/latest/topics/search/backends.html#postgresql-backend) for the wagtail search interface. Therefore, please ensure that Postgres (or PostGIS) are setup on your machine.
93
111
94
-
### 🕶 Continuous Integration
95
-
96
-
The project comes with three Continuous Integration configurations:
Simply choose one of the three and delete the others. If you don't like any of these three, feel free to use other options such as [Travis CI](https://travis-ci.org/), [Jenkins](https://jenkins.io/), etc.
103
-
104
-
## :computer: Setup
105
-
106
-
### ⌨️ to get started
112
+
### Getting Started
107
113
108
114
1. ensure that you have [cookiecutter](https://github.com/audreyr/cookiecutter) installed on your computer
109
115
2. run `cookiecutter https://github.com/engineervix/cookiecutter-wagtail-vix.git` in your favourite shell. You’ll be prompted for some values, such as **project_name**, , **project_slug**, **email**, **wagtail_user_email** etc. A new wagtail project will be created in a folder named according to the **project_slug** at your current location.
110
-
3. create a virtual environment for your project. `cd` into the project folder created above and install python dependencies: First, install [pip-tools](https://github.com/jazzband/pip-tools): `pip install pip-tools`, then run `pip-compile requirements.in` followed by `pip install -r requirements.txt`.
116
+
3. create a virtual environment for your project and and `pip install --upgrade pip`. Thereafter, `cd` into the project folder created above and install python dependencies: First, install [pip-tools](https://github.com/jazzband/pip-tools): `pip install pip-tools`, then run `pip-compile requirements.in` followed by `pip-sync`.
111
117
4. Now would be a good time to setup your postgres/postgis database and ensure that you update `DATABASE_URL` and the other environment variables in your `.env` files. The essential ones for starters are `RECAPTCHA_PUBLIC_KEY`, `RECAPTCHA_PRIVATE_KEY` and `MAPBOX_ACCESS_TOKEN`.
112
118
5.`export ENV_PATH=.envs/.dev.env`
113
-
6.`./manage.py migrate`
119
+
6.`./manage.py makemigrations` followed by `./manage.py migrate`
114
120
7.`./manage.py createsuperuser`. When prompted for an email address, please use the **wagtail_user_email** you specified in step 2. This is important to ensure that you don't have issues when populating the database with initial data, which is tied to the email address provided in step 2.
115
121
8.`./manage.py load_initial_data`
116
122
9.`yarn`
117
123
10.`gulp cp`
118
-
11. Prior to running tests, check the `package.json` to ensure that you have the correct postgres/postgis settings. Once you're all set, go ahead and run tests: `yarn test`.
124
+
11. Prior to running tests, check `package.json` to ensure that you have the correct postgres/postgis settings. Once you're all set, go ahead and run tests: `yarn test`.
119
125
12. Start the development server: `yarn dev`. Your site should be accessible at `http://127.0.0.1:3000` or `http://localhost:3000`.
120
126
121
-
### ⚙️ other steps
127
+
### Other Steps
122
128
123
129
- setup version control (git) for your generated project
124
130
- setup [pre-commit](https://pre-commit.com/):
125
131
1.`pre-commit install`
126
132
2.`pre-commit install --hook-type commit-msg`
127
-
3. Update `.git/hooks/prepare-commit-msg` with the following code:
> :exclamation: If you are using pyenv, see <https://github.com/pre-commit/pre-commit/issues/810>. In particular, I found [this explanation](https://github.com/pre-commit/pre-commit/issues/810#issuecomment-424732161) from @thomasfowler and [this comment](https://github.com/pre-commit/pre-commit/issues/810#issuecomment-602770714) from @asottile to be very helpful.
137
136
138
-
####git workflow
137
+
### git Workflow
139
138
140
139
0.:warning: First, ensure that, before you make any changes, you have pulled the latest changes from remote.
141
140
1. Add the file(s) you wanna commit: `git add whatever`
142
141
2.`git commit` -- this will run [Commitizen](http://commitizen.github.io/cz-cli/); you'll be prompted to fill in any required fields and your commit messages will be formatted according to [cz-conventional-changelog](https://github.com/commitizen/cz-conventional-changelog)– a Commitizen adapter which prompts for [conventional changelog](https://github.com/conventional-changelog/conventional-changelog) standard.
143
142
3. If there are no issues, push your changes accordingly, otherwise, repeat steps 1 and 2 above until all issues are resolved.
144
143
145
-
> :exclamation: If you encounter `stylelint` errors, you might wanna run `npm run css-fix` to try and fix such errors. This is likely to happen on first commit!
144
+
> :exclamation: If you encounter `stylelint` errors, you might wanna run `yarn css-fix` to try and fix such errors. This is likely to happen on first commit!
146
145
147
-
> :exclamation: If you make any changes to the structure of your README.md or other markdown files, do `npm run toc` before committing, so that the TOC is updated
146
+
> :exclamation: If you make any changes to the structure of your README.md or other markdown files, do `yarn toc` before committing, so that the TOC is updated
148
147
149
-
####Python Code Formatting
148
+
### Python Code Formatting
150
149
151
150
- Run `invoke lint` to run [`flake8`](https://flake8.pycqa.org/en/latest/), [`black`](https://black.readthedocs.io/en/stable/), [`isort`](https://pycqa.github.io/isort/) on the code.
152
151
- If you get any errors from `black` and/or `isort`, run `invoke lint --fix` or `invoke lint -f` so that black and isort can format your files. If this still doesn't work, don't worry, there's a bunch of pre-commit hooks that that have been set up to deal with this. Take a look at [.pre-commit-config.yaml](.pre-commit-config.yaml).
153
152
154
-
## :+1: Credits
155
-
156
-
-`.gitignore` generated using <https://www.gitignore.io/>
157
-
- favicon created using <http://realfavicongenerator.net/>
158
-
- Images courtesy of [Unsplash](https://unsplash.com/) and [Pixabay](https://pixabay.com/)
159
-
- Placeholder logo courtesy of <https://github.com/pigment/fake-logos>
160
-
-<https://loremipsum.io/> for placeholder text
161
-
- HTML template based on <https://startbootstrap.com/templates/business-frontpage/>
162
-
-_Team_ Section on **About** Page based on <https://startbootstrap.com/snippets/about-team/>
163
-
- ... I'll keep updating this ...
164
-
165
-
## ✍️ To do
153
+
## TODO ✅
166
154
167
155
### Automation
168
156
@@ -194,14 +182,40 @@ Simply choose one of the three and delete the others. If you don't like any of t
194
182
-[X] Write tests and setup CI for this cookiecutter package
195
183
-[X] Possibly add support for other popular CI options (added CircleCI and GitHub Actions)
196
184
-[X] Add `Gulp` support (No longer using `Grunt`)
197
-
-[X] Add better production-level features to make it easy to move from development to production (serving static assets, mail, caching, perfomance, task queues, Nginx and uWsgi/Gunicorn configuration, etc.) (*This is always a work in progress, will continue updating as necessary*)
185
+
-[X] Add better production-level features to make it easy to move from development to production (serving static assets, mail, caching, performance, task queues, Nginx and uWsgi/Gunicorn configuration, etc.) (*This is always a work in progress, will continue updating as necessary*)
198
186
199
187
### Deprecated
200
188
201
189
-[X]~~Add support for different Databases right from the beginning~~. Even though this cookiecuter generates an SQLite `DATABASE_URL` for you, some of the generated project's features (like **search**) depend on using Postgres, so you should use Postgres/PostGIS.
202
190
-[X]~~The cookiecutter prompt asks if you wanna use bootswatch themes. If you say "n", it shouldn't prompt you with another question on which bootswatch theme to use! See [this](https://github.com/polyswarm/participant-template/issues/2) and [that](https://github.com/cookiecutter/cookiecutter/issues/913)~~. Since we're customizing bootstrap using Sass, no need to use bootswatch.
203
191
204
-
## 📋 Reference
192
+
## Contributing 🤝
193
+
194
+
Contributions, issues and feature requests are most welcome! A good place to start is by helping out with the unchecked items in the [TODO](#todo-) section above!
195
+
196
+
Feel free to check the [issues page](https://github.com/engineervix/cookiecutter-wagtail-vix/issues) and take a look at the [contributing guide](https://github.com/engineervix/cookiecutter-wagtail-vix/blob/master/CONTRIBUTING.md) before you get started. In addition, please note the following:
197
+
198
+
- if you're making code contributions, please try and write some tests to accompany your code, and ensure that the tests pass. Also, where necessary, update the docs so that they reflect your changes.
199
+
- commit your changes via `cz commit`. Follow the prompts. When you're done, `pre-commit` will be invoked to ensure that your contributions and commits follow defined conventions. See `pre-commit-config.yaml` for more details.
200
+
- your commit messages should follow the conventions described [here](https://www.conventionalcommits.org/en/v1.0.0/). Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like `git merge` and `git revert`.
201
+
Once you are done, please create a [pull request](https://github.com/engineervix/cookiecutter-wagtail-vix/pulls).
202
+
203
+
## Show your support
204
+
205
+
Please give a ⭐️ if this project helped you!
206
+
207
+
## Credits 👏
208
+
209
+
-`.gitignore` generated using <https://www.gitignore.io/>
210
+
- favicon created using <http://realfavicongenerator.net/>
211
+
- Images courtesy of [Unsplash](https://unsplash.com/) and [Pixabay](https://pixabay.com/)
212
+
- Placeholder logo courtesy of <https://github.com/pigment/fake-logos>
213
+
-<https://loremipsum.io/> for placeholder text
214
+
- HTML template based on <https://startbootstrap.com/templates/business-frontpage/>
215
+
-_Team_ Section on **About** Page based on <https://startbootstrap.com/snippets/about-team/>
216
+
217
+
218
+
## Reference 📋
205
219
206
220
The data was dumped as follows:
207
221
@@ -210,5 +224,20 @@ The data was dumped as follows:
0 commit comments