Skip to content

Commit f85e7d6

Browse files
author
Florian Maas
authored
Contrib (#27)
* added contributing.md * changed github_author_handle name to author_github_handle
1 parent 1afe2b7 commit f85e7d6

File tree

10 files changed

+322
-21
lines changed

10 files changed

+322
-21
lines changed

‎CONTRIBUTING.rst‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
============
2+
Contributing
3+
============
4+
5+
Contributions are welcome, and they are greatly appreciated! Every little bit
6+
helps, and credit will always be given.
7+
8+
You can contribute in many ways:
9+
10+
Types of Contributions
11+
----------------------
12+
13+
Report Bugs
14+
~~~~~~~~~~~
15+
16+
Report bugs at https://github.com/fpgmaas/cookiecutter-poetry/issues
17+
18+
If you are reporting a bug, please include:
19+
20+
* Your operating system name and version.
21+
* Any details about your local setup that might be helpful in troubleshooting.
22+
* Detailed steps to reproduce the bug.
23+
24+
Fix Bugs
25+
~~~~~~~~
26+
27+
Look through the GitHub issues for bugs. Anything tagged with "bug"
28+
and "help wanted" is open to whoever wants to implement a fix for it.
29+
30+
Implement Features
31+
~~~~~~~~~~~~~~~~~~
32+
33+
Look through the GitHub issues for features. Anything tagged with "enhancement"
34+
and "help wanted" is open to whoever wants to implement it.
35+
36+
Write Documentation
37+
~~~~~~~~~~~~~~~~~~~
38+
39+
Cookiecutter PyPackage could always use more documentation, whether as part of
40+
the official docs, in docstrings, or even on the web in blog posts, articles,
41+
and such.
42+
43+
Submit Feedback
44+
~~~~~~~~~~~~~~~
45+
46+
The best way to send feedback is to file an issue at
47+
https://github.com/fpgmaas/cookiecutter-poetry/issues.
48+
49+
If you are proposing a new feature:
50+
51+
* Explain in detail how it would work.
52+
* Keep the scope as narrow as possible, to make it easier to implement.
53+
* Remember that this is a volunteer-driven project, and that contributions
54+
are welcome :)
55+
56+
Get Started!
57+
------------
58+
59+
Ready to contribute? Here's how to set up `cookiecutter-poetry` for local
60+
development. Please note this documentation assumes you already have
61+
`poetry` and `Git` installed and ready to go.
62+
63+
| 1. Fork the `cookiecutter-poetry` repo on GitHub.
64+
65+
| 2. Clone your fork locally:
66+
67+
.. code-block:: bash
68+
69+
cd <directory_in_which_repo_should_be_created>
70+
git clone [email protected]:YOUR_NAME/cookiecutter-poetry.git
71+
72+
73+
| 3. Now we need to install the environment. Navigate into the directory
74+
75+
.. code-block:: bash
76+
77+
cd cookiecutter-poetry
78+
79+
If you are using ``pyenv``, select a version to use locally. (See installed versions with ``pyenv versions``)
80+
81+
.. code-block:: bash
82+
83+
pyenv local <x.y.z>
84+
85+
Then, install and activate the environment with:
86+
87+
.. code-block:: bash
88+
89+
poetry install
90+
poetry shell
91+
92+
| 4. Create a branch for local development:
93+
94+
.. code-block:: bash
95+
96+
git checkout -b name-of-your-bugfix-or-feature
97+
98+
Now you can make your changes locally.
99+
100+
101+
| 5. Don't forget to add test cases for your added functionality to the ``tests`` directory.
102+
103+
| 6. When you're done making changes, check that your changes pass the formatting tests.
104+
105+
.. code-block:: bash
106+
107+
make lint
108+
109+
| 7. Now, validate that all unit tests are passing:
110+
111+
.. code-block:: bash
112+
113+
make test
114+
115+
| 8. Before raising a pull request you should also run tox. This will run the
116+
tests across different versions of Python:
117+
118+
.. code-block:: bash
119+
120+
tox
121+
122+
This requires you to have multiple versions of python installed.
123+
This step is also triggered in the CI/CD pipeline, so you could also choose to skip this
124+
step locally.
125+
126+
| 9. Reflect your changes in the dcoumentation. Update relevant files in the ``docs`` directory,
127+
and potentially the ``README``.You can check the updated documentation with
128+
129+
.. code-block:: bash
130+
131+
make docs
132+
133+
| 10. Commit your changes and push your branch to GitHub:
134+
135+
.. code-block:: bash
136+
137+
git add .
138+
git commit -m "Your detailed description of your changes."
139+
git push origin name-of-your-bugfix-or-feature
140+
141+
| 11. Submit a pull request through the GitHub website.
142+
143+
Pull Request Guidelines
144+
---------------------------
145+
146+
Before you submit a pull request, check that it meets these guidelines:
147+
148+
1. The pull request should include tests.
149+
150+
2. If the pull request adds functionality, the docs should be updated. Put your
151+
new functionality into a function with a docstring, and add the feature to
152+
the list in README.rst.

‎cookiecutter.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"author": "Florian Maas",
33
"email": "[email protected]",
4-
"github_author_handle" : "fpgmaas",
4+
"author_github_handle" : "fpgmaas",
55
"project_name": "example-project",
66
"project_slug": "{{cookiecutter.project_name|lower|replace('-', '_')}}",
77
"project_description": "This is a template repository for Python projects that use Poetry for their dependency management.",

‎docs/contents.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,5 @@
44
Cookiecutter Poetry <index>
55
Tutorial <tutorial>
66
Feature Details <feature_details>
7-
Prompt arguments <prompt_arguments>
7+
Prompt arguments <prompt_arguments>
8+
Contributing <contributing>

‎docs/contributing.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. include:: ../CONTRIBUTING.rst

‎docs/prompt_arguments.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ a prompt will start which enables you to configure your repository. The prompt v
2222
**email**
2323
Your email address.
2424

25-
**github_author_handle**
25+
**author_github_handle**
2626
Your github handle, i.e. ``<handle>`` in ``https://github.com/<handle>``
2727

2828
**project_name**

‎{{cookiecutter.project_name}}/CONTRIBUTING.rst‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
============
2+
Contributing
3+
============
4+
5+
Contributions are welcome, and they are greatly appreciated! Every little bit
6+
helps, and credit will always be given.
7+
8+
You can contribute in many ways:
9+
10+
Types of Contributions
11+
----------------------
12+
13+
Report Bugs
14+
~~~~~~~~~~~
15+
16+
Report bugs at https://github.com/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/issues
17+
18+
If you are reporting a bug, please include:
19+
20+
* Your operating system name and version.
21+
* Any details about your local setup that might be helpful in troubleshooting.
22+
* Detailed steps to reproduce the bug.
23+
24+
Fix Bugs
25+
~~~~~~~~
26+
27+
Look through the GitHub issues for bugs. Anything tagged with "bug"
28+
and "help wanted" is open to whoever wants to implement a fix for it.
29+
30+
Implement Features
31+
~~~~~~~~~~~~~~~~~~
32+
33+
Look through the GitHub issues for features. Anything tagged with "enhancement"
34+
and "help wanted" is open to whoever wants to implement it.
35+
36+
Write Documentation
37+
~~~~~~~~~~~~~~~~~~~
38+
39+
Cookiecutter PyPackage could always use more documentation, whether as part of
40+
the official docs, in docstrings, or even on the web in blog posts, articles,
41+
and such.
42+
43+
Submit Feedback
44+
~~~~~~~~~~~~~~~
45+
46+
The best way to send feedback is to file an issue at
47+
https://github.com/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/issues.
48+
49+
If you are proposing a new feature:
50+
51+
* Explain in detail how it would work.
52+
* Keep the scope as narrow as possible, to make it easier to implement.
53+
* Remember that this is a volunteer-driven project, and that contributions
54+
are welcome :)
55+
56+
Get Started!
57+
------------
58+
59+
Ready to contribute? Here's how to set up `{{cookiecutter.project_name}}` for local
60+
development. Please note this documentation assumes you already have
61+
`poetry` and `Git` installed and ready to go.
62+
63+
| 1. Fork the `{{cookiecutter.project_name}}` repo on GitHub.
64+
65+
| 2. Clone your fork locally:
66+
67+
.. code-block:: bash
68+
69+
cd <directory_in_which_repo_should_be_created>
70+
git clone [email protected]:YOUR_NAME/{{cookiecutter.project_name}}.git
71+
72+
73+
| 3. Now we need to install the environment. Navigate into the directory
74+
75+
.. code-block:: bash
76+
77+
cd {{cookiecutter.project_name}}
78+
79+
If you are using ``pyenv``, select a version to use locally. (See installed versions with ``pyenv versions``)
80+
81+
.. code-block:: bash
82+
83+
pyenv local <x.y.z>
84+
85+
Then, install and activate the environment with:
86+
87+
.. code-block:: bash
88+
89+
poetry install
90+
poetry shell
91+
92+
| 4. Create a branch for local development:
93+
94+
.. code-block:: bash
95+
96+
git checkout -b name-of-your-bugfix-or-feature
97+
98+
Now you can make your changes locally.
99+
100+
101+
| 5. Don't forget to add test cases for your added functionality to the ``tests`` directory.
102+
103+
| 6. When you're done making changes, check that your changes pass the formatting tests.
104+
105+
.. code-block:: bash
106+
107+
make lint
108+
109+
| 7. Now, validate that all unit tests are passing:
110+
111+
.. code-block:: bash
112+
113+
make test
114+
115+
| 8. Before raising a pull request you should also run tox. This will run the
116+
tests across different versions of Python:
117+
118+
.. code-block:: bash
119+
120+
tox
121+
122+
This requires you to have multiple versions of python installed.
123+
This step is also triggered in the CI/CD pipeline, so you could also choose to skip this
124+
step locally.
125+
126+
| 9. Commit your changes and push your branch to GitHub:
127+
128+
.. code-block:: bash
129+
130+
git add .
131+
git commit -m "Your detailed description of your changes."
132+
git push origin name-of-your-bugfix-or-feature
133+
134+
| 10. Submit a pull request through the GitHub website.
135+
136+
Pull Request Guidelines
137+
---------------------------
138+
139+
Before you submit a pull request, check that it meets these guidelines:
140+
141+
1. The pull request should include tests.
142+
143+
2. If the pull request adds functionality, the docs should be updated. Put your
144+
new functionality into a function with a docstring, and add the feature to
145+
the list in README.rst.

‎{{cookiecutter.project_name}}/README.rst‎

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,20 @@
22
{{cookiecutter.project_name}}
33
==================================
44

5-
.. image:: https://img.shields.io/github/v/release/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}
6-
:target: https://img.shields.io/github/v/release/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}
5+
.. image:: https://img.shields.io/github/v/release/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}
6+
:target: https://img.shields.io/github/v/release/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}
77
:alt: Release
88

9-
.. image:: https://img.shields.io/github/workflow/status/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}/merge-to-main
10-
:target: https://img.shields.io/github/workflow/status/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}/merge-to-main
9+
.. image:: https://img.shields.io/github/workflow/status/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/merge-to-main
10+
:target: https://img.shields.io/github/workflow/status/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/merge-to-main
1111
:alt: Build status
1212

13-
.. image:: https://img.shields.io/github/commit-activity/m/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}
14-
:target: https://img.shields.io/github/commit-activity/m/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}
13+
.. image:: https://img.shields.io/github/commit-activity/m/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}
14+
:target: https://img.shields.io/github/commit-activity/m/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}
1515
:alt: Commit activity
1616

1717
.. image:: https://img.shields.io/badge/docs-gh--pages-blue
18-
:target: https://{{cookiecutter.github_author_handle}}.github.io/{{cookiecutter.project_name}}/
18+
:target: https://{{cookiecutter.author_github_handle}}.github.io/{{cookiecutter.project_name}}/
1919
:alt: Docs
2020

2121
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
@@ -26,28 +26,28 @@
2626
:target: https://pycqa.github.io/isort/
2727
:alt: Imports with isort
2828

29-
.. image:: https://img.shields.io/github/license/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}
30-
:target: https://img.shields.io/github/license/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}
29+
.. image:: https://img.shields.io/github/license/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}
30+
:target: https://img.shields.io/github/license/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}
3131
:alt: License
3232

3333
{{cookiecutter.project_description}}
3434

35-
* **Github repository**: `https://github.com/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}/ <https://github.com/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}/>`_
36-
* **Documentation**: `https://{{cookiecutter.github_author_handle}}.github.io/{{cookiecutter.project_name}}/ <https://{{cookiecutter.github_author_handle}}.github.io/{{cookiecutter.project_name}}/>`_
35+
* **Github repository**: `https://github.com/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/ <https://github.com/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/>`_
36+
* **Documentation**: `https://{{cookiecutter.author_github_handle}}.github.io/{{cookiecutter.project_name}}/ <https://{{cookiecutter.author_github_handle}}.github.io/{{cookiecutter.project_name}}/>`_
3737

3838

3939
Releasing a new version
4040
-----------------------------
4141

4242
{% if cookiecutter.publish_to == "pypi" -%}
4343
- Create an API Token on `Pypi <https://pypi.org/>`_
44-
- Add the API Token to your projects secrets with the name ``PYPI_TOKEN`` by visiting `this page <https://github.com/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}/settings/secrets/actions/new>`_.
45-
- Create a `new release <https://github.com/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}/releases/new>`_ on Github. Create a new tag in the form ``*.*.*``.
44+
- Add the API Token to your projects secrets with the name ``PYPI_TOKEN`` by visiting `this page <https://github.com/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/settings/secrets/actions/new>`_.
45+
- Create a `new release <https://github.com/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/releases/new>`_ on Github. Create a new tag in the form ``*.*.*``.
4646

4747
For more details, see `here <https://fpgmaas.github.io/cookiecutter-poetry/releasing.html>`_.
4848
{%- elif cookiecutter.publish_to == "artifactory" -%}
49-
- Add the `ARTIFACTORY_URL`, `ARTIFACTORY_USERNAME`, and `ARTIFACTORY_PASSWORD` to your projects secrets by visiting `this page <https://github.com/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}/settings/secrets/actions/new>`_.
50-
- Create a `new release <https://github.com/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}/releases/new>`_ on Github. Create a new tag in the form ``*.*.*``.
49+
- Add the `ARTIFACTORY_URL`, `ARTIFACTORY_USERNAME`, and `ARTIFACTORY_PASSWORD` to your projects secrets by visiting `this page <https://github.com/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/settings/secrets/actions/new>`_.
50+
- Create a `new release <https://github.com/{{cookiecutter.author_github_handle}}/{{cookiecutter.project_name}}/releases/new>`_ on Github. Create a new tag in the form ``*.*.*``.
5151

5252
For more details, see `here <https://fpgmaas.github.io/cookiecutter-poetry/releasing.html>`_.
5353
{%- endif %}

0 commit comments

Comments
 (0)