|
1 | | -# Frequenz repository common configuration for Python |
| 1 | +# Frequenz Repository Configuration |
2 | 2 |
|
3 | | -This is very opinionated set of tools and configurations to setup a Python |
4 | | -repository for Frequenz projects. |
| 3 | +[](https://github.com/frequenz-floss/frequenz-repo-config-python/actions/workflows/ci.yaml) |
| 4 | +[](https://pypi.org/project/frequenz-repo-config/) |
| 5 | +[](https://frequenz-floss.github.io/frequenz-repo-config-python/) |
5 | 6 |
|
6 | | -If offers: |
| 7 | +## Introduction |
7 | 8 |
|
8 | | -* [Cookiecutter] templates for scaffolding new projects |
9 | | -* Trivial build of `noxfile.py` with some predefined sessions with all common |
10 | | - checks. |
11 | | -* Tools to build protobuf/grpc files as Python, including type information. |
| 9 | +This is a highly opinionated set of tools and configurations to set up a Python |
| 10 | +repository for [Frequenz](https://frequenz.com) projects. |
12 | 11 |
|
| 12 | +It offers: |
13 | 13 |
|
14 | | -[Cookiecutter]: https://cookiecutter.readthedocs.io/en/stable |
| 14 | +* [Cookiecutter] templates for scaffolding new projects |
| 15 | +* Trivial build of `noxfile.py` with some predefined sessions that include all |
| 16 | + common checks. |
| 17 | +* Tools to build protobuf/grpc files as Python, including type information. |
15 | 18 |
|
16 | | -## Start a new project |
| 19 | +## Quick Example |
17 | 20 |
|
18 | | -To start a new project you should first [install |
| 21 | +To start a new project, you should first [install |
19 | 22 | Cookiecutter](https://cookiecutter.readthedocs.io/en/stable/installation.html). |
20 | 23 | It is normally available in any Linux distribution, but some have a very old |
21 | | -version (for example, Ubuntu/Debian). You can [check which version your distro |
22 | | -has in Repology](https://repology.org/project/cookiecutter/versions). You need |
23 | | -**at least version 2.1.0**. To make sure to get an up to date version you can |
24 | | -always uses `pip` and install in a `venv`: |
| 24 | +version (for example, Ubuntu/Debian). You can [check which version your distro |
| 25 | +has on Repology](https://repology.org/project/cookiecutter/versions). You need |
| 26 | +**at least version 2.1.0**. To ensure you get an up-to-date version, you can |
| 27 | +always use `pip` and install it in a `venv`: |
25 | 28 |
|
26 | 29 | ```console |
27 | 30 | $ python -m venv cookiecutter |
28 | 31 | $ cd cookiecutter |
29 | 32 | $ . bin/activate |
30 | | -[cookiecutter] $ pip install cookiecutter |
| 33 | +(venv) $ pip install cookiecutter |
31 | 34 | Collecting cookiecutter |
32 | 35 | ... |
33 | 36 | ``` |
34 | 37 |
|
35 | | -Then just run cookiecutter where you want to create the new project. A new |
| 38 | +Then simply run [Cookiecutter] where you want to create the new project. A new |
36 | 39 | directory will be created with the generated project name. For example: |
37 | 40 |
|
38 | 41 | ```sh |
39 | 42 | cd ~/devel |
40 | 43 | cookiecutter gh:frequenz-floss/frequenz-repo-config-python --directory=cookiecutter |
41 | 44 | ``` |
42 | 45 |
|
43 | | -This will prompt for the project type, name and other configuration and |
44 | | -generate the whole project for you. |
45 | | - |
46 | | -After completing it and fixing the TODOs |
47 | | -you can amend the previous commit using `git commit --amend` |
48 | | -or create a new commit for the changes using `git commit`. |
49 | | -You can make sure linting and tests pass by creating a virtual |
50 | | -environment, installing the development dependencies and running `nox`: |
51 | | -```sh |
52 | | -# requires at least python version 3.11 |
53 | | -python3 -m venv .venv |
54 | | -. .venv/bin/activate |
55 | | -pip install .[dev-noxfile] |
56 | | -nox |
57 | | -``` |
58 | | - |
59 | | -## Migrating an existing project |
60 | | - |
61 | | -The easiest way to migrate an existing project is to just generate a new one |
62 | | -basing all the inputs in the current project metadata and then overwritting the |
63 | | -existing files. |
64 | | - |
65 | | -It is recommended to commit all changes before doing this, so you can then use |
66 | | -`git` to look at the changes. |
67 | | - |
68 | | -If you generate the new repo in a temporary directory, you can easily overwrite |
69 | | -the files in your existing project by using `rsync` or similar tools: |
70 | | - |
71 | | -```sh |
72 | | -cd /tmp |
73 | | -cookiecutter gh:frequenz-floss/frequenz-repo-config-python --directory=cookiecutter |
74 | | -rsync -vr --exclude=.git/ new-project/ /path/to/existing/project |
75 | | -cd /path/to/existing/project |
76 | | -git diff |
77 | | -# Fix all the `TODO`s and cleanup the generated files |
78 | | -git commit -a |
79 | | -``` |
| 46 | +This command will prompt you for the project type, name, and other |
| 47 | +configuration options, and it will generate the entire project for you. |
80 | 48 |
|
81 | | -!!! warning |
| 49 | +After completing the project and fixing the `TODO`s, you can either amend the |
| 50 | +previous commit using `git commit --amend` or create a new commit for the |
| 51 | +changes using `git commit`. |
82 | 52 |
|
83 | | - The trailing slash in `new-project/` and the lack of it in |
84 | | - `/path/to/existing/project` are meaningful to `rsync`. |
| 53 | +## Documentation |
85 | 54 |
|
86 | | - Also make sure to **exclude** the `.git/` directory to avoid messing up |
87 | | - with your local git repository. |
88 | | - |
89 | | -## Update an existing project |
90 | | - |
91 | | -To update an existing project you can use the [Cookiecutter *replay |
92 | | -file*](https://cookiecutter.readthedocs.io/en/stable/advanced/replay.html) that |
93 | | -was saved during the project generation. The file is saved in |
94 | | -`.cookiecutter-replay.json`. Using this file you can re-run Cookiecutter |
95 | | -without having to enter all the inputs again. |
96 | | - |
97 | | -!!! warning |
98 | | - |
99 | | - Don't forget to commit all changes in your repository before doing this! |
100 | | - Files will be overwritten! |
101 | | - |
102 | | -```sh |
103 | | -git commit -a # commit all changes |
104 | | -cd .. |
105 | | -cookiecutter gh:frequenz-floss/frequenz-repo-config-python \ |
106 | | - --directory=cookiecutter \ |
107 | | - --force \ |
108 | | - --replay \ |
109 | | - --replay-file project-directory/.cookiecutter-replay.json |
110 | | -``` |
111 | | - |
112 | | -This will create a new commit with all the changes to the overwritten files. |
113 | | -Bear in mind that all the `TODO`s will come back, so there will be quite a bit |
114 | | -of cleanup to do. You can easily check what was changed using `git show`, and |
115 | | -you can use `git commit --amend` to amend the previous commit with the template |
116 | | -updates, or create a new commit with the fixes. You can also use `git citool` |
117 | | -or `git gui` to easily add, remove or even discard (revert) changes in the |
118 | | -templates update commit. |
119 | | - |
120 | | -!!! note |
121 | | - |
122 | | - The `project-directory` is the directory of your previously generated |
123 | | - project. If you renamed it, then the files will be generated in a new |
124 | | - directory with the original name. You can update the target directory in |
125 | | - the replay file. |
126 | | - |
127 | | -!!! note |
128 | | - |
129 | | - Please remember to keep your replay file up to date if you change any |
130 | | - metadata in the project. |
| 55 | +For more detailed documentation, please check the [project's |
| 56 | +website](https://frequenz-floss.github.io/frequenz-repo-config-python/). |
131 | 57 |
|
132 | 58 | ## Contributing |
133 | 59 |
|
134 | 60 | If you want to know how to build this project and contribute to it, please |
135 | | -check out the [Contributing Guide](CONTRIBUTING.md). |
| 61 | +refer to the [Contributing Guide](CONTRIBUTING.md). |
| 62 | + |
| 63 | + |
| 64 | +[Cookiecutter]: https://cookiecutter.readthedocs.io/en/stable |
0 commit comments