Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 279456a

Browse files
Mr-SunglassesMr-Sunglasses
authored
Update CONTRIBUTING.md
1 parent a758d3e commit 279456a

File tree

1 file changed

+117
-73
lines changed

1 file changed

+117
-73
lines changed

‎CONTRIBUTING.md‎

Lines changed: 117 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -1,118 +1,162 @@
1-
## Contributing Guidelines
1+
# paste.py
22

3-
First off, thank you for considering contributing to `paste.py 🐍`. This guide details all the general information that one should know before contributing to the project.
4-
Please stick as close as possible to the guidelines. That way, we ensure that you have a smooth experience contributing to this project.
3+
<a href="https://kuma.fosscu.org/status/pastepy" target="_blank"><img src="https://badgen.net/badge/status/paste.py/green?icon=lgtm" alt=""></a>
54

6-
### General Rules:
5+
<hr>
76

8-
These are, in general, rules that you should be following while contributing to an Open-Source project :
7+
paste.py 🐍 - A pastebin written in python.
98

10-
- Be Nice, Be Respectful (BNBR)
11-
- Check if the Issue you created, exists or not.
12-
- While creating a new issue, make sure you describe the issue clearly.
13-
- Make proper commit messages and document your PR well.
14-
- Always add comments in your Code and explain it at points if possible, add Doctest.
15-
- Always create a Pull Request from a Branch; Never from the Main.
16-
- Follow proper code conventions because writing clean code is important.
17-
- Issues would be assigned on a "First Come, First Served" basis.
18-
- Do mention (@maintainer) the project maintainer if your PR isn't reviewed within a few days.
9+
# 🤔 Pre-requisites
1910

20-
## First time contributors:
11+
- `python3`
12+
- `pdm`
2113

22-
Pushing files in your own repository is easy, but how to contribute to someone else's project? If you have the same question, then below are the steps that you can follow
23-
to make your first contribution in this repository.
14+
## 🐍 Python Version Support
2415

25-
### Pull Request
16+
This project is designed to be compatible with specific versions of Python for optimal performance and stability.
2617

27-
**1.** The very first step includes forking the project. Click on the `fork` button as shown below to fork the project.
28-
<br><br><img src="https://i.imgur.com/7wapvt2.png" width="750" /><br>
18+
### Supported Python Version
2919

30-
**2.** Clone the forked repository. Open up the GitBash/Command Line and type
20+
- **Python 3.11.3**
3121

32-
```
33-
git clone https://github.com/<YOUR_USER_NAME>/paste.py.git
34-
```
22+
> ❗️ For the best experience and performance, it is recommended to use the version mentioned above.
3523
36-
**3.** Navigate to the project directory.
24+
Before diving into the project, ensure that you have the correct Python version installed. To check the version of Python you currently have, execute the following command in your terminal:
3725

38-
```
39-
cd paste.py
26+
```bash
27+
python --version
4028
```
4129

42-
**4.** Add a reference to the original repository.
30+
### 🐍 Installing Python 3.11.3 with `pyenv`
4331

44-
```
45-
git remote add upstream https://github.com/FOSS-Community/paste.py.git
46-
```
32+
**Protip:** Managing multiple Python versions is a breeze with [pyenv](https://github.com/pyenv/pyenv). It allows you to seamlessly switch between different Python versions without the need to reinstall them.
4733

48-
**5.** See latest changes to the repo using
34+
If you haven't installed `pyenv` yet, follow their [official guide](https://github.com/pyenv/pyenv) to set it up.
4935

50-
```
51-
git remote -v
36+
Once you have `pyenv` ready, install the recommended Python version by running:
37+
38+
```bash
39+
pyenv install 3.11.3
5240
```
5341

54-
**6.** Create a new branch.
42+
> When you navigate to this project's directory in the future, `pyenv` will automatically select the recommended Python version, thanks to the `.python-version` file in the project root.
5543
56-
```
57-
git checkout -b <YOUR_BRANCH_NAME>
58-
```
44+
# 📦 Setup
5945

60-
**7.** Always take a pull from the upstream repository to your main branch to keep it even with the main project. This will save you from frequent merge conflicts.
46+
## Local setup 🛠️ with Docker 🐳
6147

62-
```
63-
git pull upstream main
64-
```
48+
- **Installing and running**:
49+
Before you begin, ensure you have docker installed. If not, refer to the [official documentation](https://docs.docker.com/engine/install/) to install docker.
50+
```bash
51+
docker pull mrsunglasses/pastepy
52+
docker run -d -p 8080:8080 --name pastepyprod mrsunglasses/pastepy
53+
```
6554

66-
**8.** You can make the required changes now. Make appropriate commits with proper commit messages.
55+
## Local setup 🛠️ without Docker 🐳
6756

68-
**9.** Add and then commit your changes.
57+
### Setting Up the Project with PDM
6958

70-
```
71-
git add .
72-
```
59+
[PDM (Python Development Master)](https://pdm.fming.dev/latest/) is utilized for dependency management in this project. To set up and run the project:
7360

61+
- **Installing PDM**:
62+
Before you begin, ensure you have PDM installed. If not, refer to the [official documentation](https://pdm.fming.dev/latest/) to install PDM.
63+
64+
- **Clone the Repository**:
65+
Get the project source code from GitHub:
66+
67+
```bash
68+
git clone https://github.com/FOSS-Community/paste.py.git
69+
```
70+
71+
- **Navigate to the Project Directory**:
72+
73+
```bash
74+
cd paste.py
75+
```
76+
77+
- **Install Dependencies**:
78+
Use PDM to install the project's dependencies:
79+
```bash
80+
pdm install
81+
```
82+
83+
* **Start the Project**:
84+
Use PDM to run the project:
85+
```bash
86+
pdm run start
87+
```
88+
- You can also use `pdm run dev` to start the dev server.
89+
90+
## Setting Up and Testing the Project
91+
92+
To ensure the code quality and functionality of the project, follow the steps below:
93+
94+
### Installing Git Hooks with `pre-commit`
95+
96+
Before making any commits, it's essential to ensure that your code meets the quality standards. This project utilizes `pre-commit` hooks to automatically check your changes before any commit.
97+
98+
Install the pre-commit hooks with the following command:
99+
100+
```bash
101+
pre-commit install
74102
```
75-
git commit -m "<YOUR_COMMIT_MESSAGE>"
76-
```
77103

78-
**10.** Push your local branch to the remote repository.
104+
### Running Tests
105+
106+
To ensure the project's functionality, you should run all the provided tests. Execute the following command to run the tests:
79107

108+
```bash
109+
pdm run test
80110
```
81-
git push -u origin <YOUR_BRANCH_NAME>
111+
112+
### Testing the Running Server
113+
114+
Once you have your server up and running, you can send requests to it from another terminal to test its responsiveness and functionality.
115+
116+
Here are a couple of `GET` requests you can make using [curl](https://curl.se/):
117+
118+
```bash
119+
curl http://0.0.0.0:8080/health
82120
```
83121

84-
**11.** Once you have pushed the changes to your repository, go to your forked repository. Click on the `Compare & pull request` button as shown below.
85-
<br><br><img src="https://hisham.hm/img/posts/github-comparepr.png" width="750" /><br>
122+
> These endpoints typically return the health status or readiness of the server, helping in diagnostics and monitoring.
123+
124+
# 🗒️ How to contribute
86125

87-
**12.** The image below is what the new page would look like. Give a proper title to your PR and describe the changes made by you in the description box.(Note - Sometimes there are PR templates which are to be filled as instructed.)
88-
<br><br><img src="https://github.blog/wp-content/uploads/2019/02/draft-pull-requests.png?fit=1354%2C780" width="750" /><br>
126+
> ❗️Important: **Please read the [Code of Conduct](CODE_OF_CONDUCT.md) and go through [Contributing Guideline](CONTRIBUTING.md) before contributing to paste.py**
89127
90-
**13.** Open a pull request by clicking the `Create pull request` button.
128+
- Feel free to open an issue for any clarifications or suggestions.
91129

92-
`Voila, you have made your first contribution to this project`
130+
<hr>
93131

94-
## Issue
132+
## Uasge:
95133

96-
- Issues can be used to keep track of bugs, enhancements, or other requests. Creating an issue to let the project maintainers know about the changes you are planning to make before raising a PR is a good open-source practice.
97-
<br>
134+
### Uisng CLI
98135

99-
Let's walk through the steps to create an issue:
136+
> cURL is required to use the CLI.
100137
101-
**1.** On GitHub, navigate to the main page of the repository. [Here](https://github.com/blossomlabsio/Bloom-Backend.git) in this case.
138+
- Paste a file named 'file.txt'
139+
140+
```bash
141+
curl -X POST -F "[email protected]" https://paste.fosscu.org/file
142+
```
102143

103-
**2.** Under your repository name, click on the `Issues` button.
104-
<br><br><img src="https://www.stevejgordon.co.uk/wp-content/uploads/2018/01/GitHubIssueTab.png" width="750" /><br>
144+
- Paste from stdin
105145

106-
**3.** Click on the `New issue` button.
107-
<br><br><img src="https://miro.medium.com/max/3696/1*8jiGiKhMdVQDycWSAbjB8A.png" width="750" /><br>
146+
```bash
147+
echo "Hello, world." | curl -X POST -F "file=@-" https://paste.fosscu.org/file
148+
```
149+
150+
- Delete an existing paste
151+
152+
```bash
153+
curl -X DELETE https://paste.fosscu.org/paste/<id>
154+
```
108155

109-
**4.** Select one of the Issue Templates to get started.
110-
<br><br><img src="https://i.imgur.com/xz2KAwU.png" width="750" /><br>
156+
### Using the web interface:
111157

112-
**5.** Fill in the appropriate `Title` and `Issue description` and click on `Submit new issue`.
113-
<br><br><img src="https://i.imgur.com/XwjtGG1.png" width="750" /><br>
158+
[Go here](https://paste.fosscu.org/web)
114159

115-
### Tutorials that may help you:
160+
<hr>
116161

117-
- [Git & GitHub Tutorial](https://www.youtube.com/watch?v=RGOj5yH7evk)
118-
- [Resolve merge conflict](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github)
162+
For info API usage and shell functions, see the [website](https://paste.fosscu.org).

0 commit comments

Comments
 (0)