Skip to content

Commit 851a066

Browse files
delphidabblerdelphidabbler
committed
Merge branch 'feature/104-overhaul-main-readme' into develop
Closes #104
2 parents 000dfdd + 20ab214 commit 851a066

File tree

3 files changed

+260
-82
lines changed

3 files changed

+260
-82
lines changed

‎CONTRIBUTING.md

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Contributing
2+
3+
Thanks for you interest in contributing to the CodeSnip project.
4+
5+
## Contents
6+
7+
* [Overview](#overview)
8+
* [Issues](#issues)
9+
* [Documentation](#documentation)
10+
* [Coding](#coding)
11+
* [About Pull Requests](#about-pull-requests)
12+
* [Licensing of Contributions](#licensing-of-contributions)
13+
* [Code of Conduct](#code-of-conduct)
14+
* [Attributions](#attributions)
15+
16+
## Overview
17+
18+
Contributions of all kinds are more than welcome.
19+
20+
> 💡 You will need a GitHub account to be able to make contributions. [Sign up here](https://docs.github.com/en/get-started/signing-up-for-github/signing-up-for-a-new-github-account).
21+
22+
There three main ways in which you can contribute, each of which is explained in its own section below. From easiest to hardest, they are:
23+
24+
* [Issues](#issues) - report bugs and request new features.
25+
* [Documentation](#documentation) - improve the project's documentation.
26+
* [Coding](#coding) - modify the project's source code.
27+
28+
Regardless of how you choose to contribute, please respect the project's [code of conduct](#code-of-conduct).
29+
30+
## Issues
31+
32+
The easiest way to make a contribution is to [create an issue](https://github.com/delphidabbler/codesnip/issues/new).
33+
34+
You can use issues to:
35+
36+
1. [Report a bug](#reporting-a-bug)
37+
2. [Request a new program feature](#requesting-a-new-feature)
38+
3. [Suggest changes to documentation](#suggesting-documentation-changes)
39+
40+
It is helpful if you perform a cursory search of [existing issues](https://github.com/delphidabbler/codesnip/issues?q=is%3Aissue) to see if there is already a similar issue. If so then please add your thoughts as comments on that issue rather than open a new one.
41+
42+
### Reporting a bug
43+
44+
Before reporting a bug please make sure the bug exists in the [latest release](https://github.com/delphidabbler/codesnip/releases) of CodeSnip 4.
45+
46+
To report a bug please provide as much information about the bug as possible, including the program's version number, what happened, what you expected to happen and what you were doing at the time. If possible, explain how to reproduce the bug.
47+
48+
> 💡 You can find CodeSnip's version number in the program's About box (_Help | About_ menu option).
49+
50+
If you have resolved an issue yourself please consider contributing your fix so that others can benefit from your work. Please read the [Coding](#coding) section before doing so.
51+
52+
### Requesting a new feature
53+
54+
If you think of a feature that you would like to see added to CodeSnip you can open an issue to request it.
55+
56+
Please be as clear as possible about what you expect the feature to do and why you want it.
57+
58+
Ideas about how to implement the feature are welcome. Even better, if you have implemented the feature yourself, you may be able to contribute the code. But please read the [Coding](#coding) section before doing so.
59+
60+
### Suggesting documentation changes
61+
62+
The third reason to create an issue is if you want to suggest new documentation or ammendments to existing documentation.
63+
64+
There are two types of documentation within the CodeSnip repository. Firstly, there is general documentation that can be found in the [repository root](https://github.com/delphidabbler/codesnip/tree/develop) and in the [`Docs`](https://github.com/delphidabbler/codesnip/tree/develop/Docs) directory. Secondly, there are numerous HTML help files in the [`Src/Help/HTML`](https://github.com/delphidabbler/codesnip/tree/develop/Src/Help/HTML) directory.
65+
66+
If you have written or corrected some documentation yourself please consider submitting it. See the [Documentation](#documentation) section below to find out how to do this.
67+
68+
## Documentation
69+
70+
Writing and editing documentation is a relatively easy way to start contributing. Providing simple clear or helpful documentation for users is critical. Things that *you* found hard to understand as a user, or difficult to work out, are excellent places to begin.
71+
72+
There are two ways to contribute documentation. The preferred method is by means of a [pull request](#about-pull-requests). But, you can simply create an issue and attach documentation files to the issue comments. This approach is perfectly acceptable for a small number of files, and saves you having to install Git!
73+
74+
## Coding
75+
76+
Code contributions to the [CodeSnip 4 development tree](https://github.com/delphidabbler/codesnip/tree/develop) are always welcome, from fixing bugs to developing new features.
77+
78+
> 🐘 Before going any further, let's address the elephant in the room. CodeSnip has to be compiled with the now rather ancient Delphi XE. It would be much better if development could move to a more recent version of Delphi, but that's proving to be extremely problematic. See [this FAQ](https://github.com/delphidabbler/codesnip-faq/blob/master/SourceCode.md#faq-11) for an explanation.
79+
80+
If you're still here, you will need to set up a valid build environment in order to compile CodeSnip from source. [`Build.html`](https://htmlpreview.github.io/?https://github.com/delphidabbler/codesnip/blob/develop/Build.html) tells you everything you need to know about configuring the environment, the tools you will need, and how compile CodeSnip using the provided `Makefile`.
81+
82+
> 💡 Need ideas? You can [browse open issues](https://github.com/delphidabbler/codesnip/issues) and see if you can help with any of them.
83+
84+
Contributions should normally be made using [pull requests](#about-pull-requests).
85+
86+
But, if you have just a few lines of code to suggest it _may_ be possible to accept the code within (or attached to) a comment on an issue. If in doubt, ask first by means of a comment. When including the code in a comment, please use [GitHub code fencing](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks) to format the code and make it easier to read. For example:
87+
88+
```pascal
89+
procedure TFoo.CoolNewMethod;
90+
begin
91+
// cool code here
92+
end;
93+
```
94+
95+
## About Pull Requests
96+
97+
All pull requests *must* relate to an [open _accepted_ issue](https://github.com/delphidabbler/codesnip/issues?q=is%3Aissue+label%3Aaccepted++is%3Aopen+) on GitHub.
98+
99+
If you wish to contribute code for which there is no existing issue you can create one. Please wait for the issue to be accepted by the project owner before submitting your pull request. Acceptance is indicated by attaching an "accepted" label to the issue and is signed off by means of a comment on the issue from the project owner.
100+
101+
> 💡 Should you get stuck at any point please ask for help by leaving a comment on the relevant issue.
102+
103+
Before you can start you need to get the source code. Here's how:
104+
105+
1. Fork the CodeSnip project into your own GitHub repository.
106+
107+
⭐***Important***⭐ _Ensure that all remote branches are included in the fork_, not just `master`. On GitHub this means clearing the "Copy the `master` branch only" check box before creating the fork.
108+
109+
2. Clone the forked repository onto your own system using:
110+
111+
$ git clone https://github.com/<account>/codesnip.git
112+
113+
where `<account>` is your GitHub user account ID.
114+
115+
CodeSnip uses the [Git Flow](https://nvie.com/posts/a-successful-git-branching-model/) methodology. This means that you need to create your source code on a "feature" branch off the `develop` branch. Here's how:
116+
117+
1. Pull the `develop` branch from your forked repository, and switch into it:
118+
119+
$ git pull origin develop
120+
$ git switch develop
121+
122+
2. Create and switch to a new feature branch, branched off `develop`.
123+
124+
Name the branch `feature/` followed by the issue number to which it relates. Appending a hyphen followed by a brief description is useful too. Example branch names are `feature/42-fix-ui-bug` or `feature/56`:
125+
126+
$ git branch feature/42-fix-ui-bug
127+
$ git switch feature/42-fix-ui-bug
128+
129+
3. Make your changes, whether to source code or documentation, and commit them to your feature branch. Clarity is prefered to terseness in commit messages. Please don't squash logically unrelated commits.
130+
131+
4. If you are editing source code you need to ensure that it compiles and works as expected.
132+
133+
> 💡 Having trouble? Please make sure you have read [`Build.html`](https://htmlpreview.github.io/?https://github.com/delphidabbler/codesnip/blob/develop/Build.html). If that doesn't solve your problem then ask for help by creating a comment on the relevant issue.
134+
135+
Once you have finished writing the code and are ready to submit it you need to prepare your forked repository:
136+
137+
1. Use GitHub to ensure that the `develop` branch of your fork is up to date with the parent `delphidabbler/codesnip` repository's `develop` branch.
138+
139+
2. Rebase your changes onto your forked repository's remote `develop` branch:
140+
141+
$ git rebase origin/develop feature/42-fix-ui-bug
142+
143+
3. Resolve any conflicts arising from the rebase then push your changes to your forked repository:
144+
145+
$ git push origin feature/42-fix-ui-bug
146+
147+
You are finally ready to open that pull request. Proceed as follows:
148+
149+
1. Open your forked repository on GitHub. You should see a banner saying something like "feature/42-fix-ui-bug had recent pushes ..." along with a button that says "Compare and Pull Request". Click that button.
150+
151+
2. You will be taken the "Comparing Changes" page on `delphidabbler/codesnip`.
152+
153+
⭐***Important***⭐ Just below the page title is a line of drop-down buttons where you choose what to compare. Check the caption of the 2nd button from the left. If it reads anything other than "base: `develop`" (and it probably doesn't) then click the button and select `develop` from the list of branches that is displayed.
154+
155+
> ⚠️ Pull requests based on `master`, or any branch other than `develop`, will not be accepted.
156+
157+
3. Now complete the form and click the "Create Pull Request" button.
158+
159+
That's it.
160+
161+
Sit back and wait. Either your pull request will be accepted or you will receive comments requesting clarification or changes.
162+
163+
Once your pull request is accepted you can delete the feature branch from both your local and forked remote fork.
164+
165+
## Licensing of Contributions
166+
167+
The license that applies to any existing file you edit will continue to apply to the edited file. Any existing license text or copyright statement **must not** be altered or removed, but you can add your own copyright line if desired.
168+
169+
Any new file you contribute **must** either be licensed under the [Mozilla Public License v2.0](https://www.mozilla.org/MPL/2.0/) (MPL2) or have a license compatible with the MPL2. If a license is not specified then MPL2 will be assumed and will be applied to the file. You should insert a suitable copyright statement in the file.
170+
171+
Any third party code used by your contributed code **must** also have a license compatible with the MPL2.
172+
173+
> 💡 MPL2 boilerplate text, in several programming language's comment formats, can be found in the file [`Docs/MPL-2.0-Boilerplate.txt`](https://raw.githubusercontent.com/delphidabbler/codesnip/master/Docs/MPL-2.0-Boilerplate.txt). You will need to change the name of the copyright holder.
174+
175+
## Code of Conduct
176+
177+
This is a simple and straightforward code of conduct. What it boils down to is that if you're a decent person you're more than welcome here. Hateful, abusive and just plain rude people are not.
178+
179+
To be more precise, anyone who contributes to the CodeSnip project is expected to display respect, empathy and politeness towards others.
180+
181+
Certain behaviours will not be tolerated, and will result in an immediate ban. They are:
182+
183+
* Racism and hate speech in any form.
184+
* The use of sexualized language or imagery, and sexual attention or advances of any kind.
185+
* Intolerance towards people of any religion or none.
186+
* Trolling, insulting or derogatory comments, and personal or political attacks.
187+
* Public or private harassment.
188+
* Publishing others' private information, such as a physical or email address, without their explicit permission.
189+
* Other conduct which could reasonably be considered inappropriate in a professional setting.
190+
191+
## Attributions
192+
193+
1. The list of unacceptable behaviours in the Code of Conduct was taken, in part, from the "Our Standards" section of the [Contributor Covenant Code of Conduct v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
194+
195+
2. Some of the content of this document was inspired by and/or copied from the [Stumpy Contributing Guide](https://stumpy.readthedocs.io/en/latest/Contribute.html).

‎Docs/ReadMe.txt

Lines changed: 32 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -48,14 +48,15 @@ Installation
4848
================================================================================
4949

5050
CodeSnip requires Windows 2000 or later. It also requires MS Internet Explorer 6
51-
or later, but IE 8, 9 or 10 are strongly recommended.
51+
or later, although IE 8, 9 or 10 are strongly recommended. But note that recent
52+
releases have only been tested on Windows 10/11.
5253

5354
Installing the Standard Edition
5455
-------------------------------
5556

5657
You will need administrator privileges to run the setup program for the standard
5758
edition. If you are using a non-admin user account on Windows 2000 or XP you
58-
should run setup as administrator. By default Windows Vista to Windows 10 will
59+
should run setup as administrator. By default Windows Vista to Windows 11 will
5960
require an admin password if running as a standard user and setup will attempt
6061
to elevate the process. If UAC prompts are disabled you must run setup as
6162
administrator.
@@ -66,8 +67,8 @@ usual way. Uninstalling v3 or earlier after installing v4 will have no adverse
6667
affect on v4.
6768

6869
CodeSnip's installation program is named codesnip-setup-4.x.x.exe, where x.x
69-
is the program's minor version number. The install program may be distributed in
70-
a zip file.
70+
is the program's minor version number. The install program is distributed in a
71+
zip file.
7172

7273
Close any running instance of CodeSnip, run the install program then follow the
7374
on-screen instructions.
@@ -80,9 +81,9 @@ The installer makes the following changes to your system:
8081
+ Files required by the uninstaller are stored in the main installation's Uninst
8182
sub-folder.
8283

83-
+ The program's uninstall information is registered with the "Apps and Features"
84-
(a.k.a. "Programs and Features", a.k.a. "Add / Remove Programs") control panel
85-
applet.
84+
+ The program's uninstall information is registered with the "Installed App"
85+
(a.k.a. "Apps and Features", a.k.a. "Programs and Features", a.k.a. "Add /
86+
Remove Programs") control panel app.
8687

8788
+ A program group may be created in the start menu (optional).
8889

@@ -113,9 +114,10 @@ the program executable, the help file and various documentation files.
113114

114115
Install the program using the following steps:
115116

116-
1) Mount the storage medium on which you want to install CodeSnip.
117+
1) Mount any storage medium on which you want to install CodeSnip.
117118

118-
2) Create a folder on the storage medium in which to copy the required files.
119+
2) Create a folder on the storage medium or on your computer's internal disk in
120+
which to copy the required files.
119121

120122
3) Copy the files CodeSnip-p.exe (the executable program) and CodeSnip.chm
121123
(the help file) into the folder you created.
@@ -143,12 +145,13 @@ Uninstallation
143145
Uninstalling the Standard Edition
144146
---------------------------------
145147

146-
CodeSnip can be uninstalled via "Apps and Features" (a.k.a. "Programs and
147-
Features", a.k.a. "Add / Remove Programs") from the Windows Control Panel or by
148-
choosing "Uninstall DelphiDabbler CodeSnip" from the program's start menu group.
148+
CodeSnip can be uninstalled via "Installed Apps" (a.k.a. "Apps and Features",
149+
a.k.a. "Programs and Features", a.k.a. "Add / Remove Programs") accessed from the
150+
Windows Control Panel or by choosing "Uninstall DelphiDabbler CodeSnip" from the
151+
program's start menu group.
149152

150153
Administrator privileges will be required to uninstall CodeSnip. Windows Vista
151-
to Windows 10 with UAC prompts enabled will prompt for an admin password if
154+
to Windows 11 with UAC prompts enabled will prompt for an admin password if
152155
necessary.
153156

154157
The uninstall program will delete any local copy of the online Code Snippets
@@ -205,12 +208,15 @@ Windows 32 version of Delphi (from Delphi 2 to Delphi 11.x Alexandria) and
205208
FreePascal, providing some simple rules are followed.
206209

207210
When CodeSnip is first installed it knows nothing about the available compilers
208-
and so test compilations cannot be performed. You must tell CodeSnip about the
209-
available compilers by using the "Tools | Configure Compilers" menu option. The
210-
resulting dialogue can automatically detect all installed versions of supported
211-
Delphi compilers at the click of a button. Free Pascal, where installed, must be
212-
set up manually. The Welcome page displays a list of compilers it has been
213-
configured to work with.
211+
and so test compilations cannot be performed. If any supported Delphi compiler
212+
is detected when the program is first run you will be given the option of
213+
registering it. This does not work for Free Pascal.
214+
215+
You can also tell CodeSnip about the available compilers by using the "Tools |
216+
Configure Compilers" menu option. The resulting dialogue can automatically
217+
detect all installed versions of supported Delphi compilers at the click of a
218+
button. Free Pascal, where installed, must be set up manually. The Welcome page
219+
displays a list of compilers it has been configured to work with.
214220

215221
Compilers that do not use English as their output language will need further
216222
configuration. See the help file for information (look up "configure compilers
@@ -221,19 +227,16 @@ Each user can configure compilers differently.
221227
Delphi XE2 and later may need to be configured to search for required units in
222228
the correct namespaces. This is explained in the Add/Edit Snippet Dialogue Box
223229
help topic and in the FAQ at
224-
https://github.com/delphidabbler/codesnip-faq/blob/master/UsingCodeSnip.md#faq-1
230+
https://github.com/delphidabbler/codesnip-faq/blob/master/UsingCodeSnip.md#faq-7
225231

226232
Any type of snippet other than "freeform" can be test compiled.
227233

228234

229235
Updating the Program
230236
================================================================================
231237

232-
Updates are published on:
233-
234-
+ GitHub: https://github.com/delphidabbler/codesnip/releases
235-
236-
+ SourceForge: https://sourceforge.net/projects/codesnip/files/
238+
Updates are published on GitHub. See
239+
https://github.com/delphidabbler/codesnip/releases
237240

238241
News of new updates is published on the CodeSnip Blog:
239242
https://codesnip-app.blogspot.com/.
@@ -324,9 +327,8 @@ If you wish to report a bug, please check the current reports on the bug
324327
tracker. If your bug hasn't already been reported or fixed please add a report
325328
using the "Add new" link on Tracker.
326329

327-
Please note that version 4.15.1 and earlier are no longer supported, so don't
328-
report bugs for those versions. You should update the program first and only
329-
report the bug if it is still present.
330+
Please ensure that you have installed the latest version of CodeSnip and checked
331+
if the bug is still present before reporting it.
330332

331333

332334
Feedback
@@ -378,8 +380,8 @@ Thanks to:
378380

379381
+ Various contributors to the DelphiDabbler Code Snippets database. Names of
380382
contributors are listed in the program's About Box (use the "Help | About"
381-
menu option then select the "About the Database" tab). If the list is empty
382-
then updating the Code Snippets Database will download the details.
383+
menu option then select the "About the Database" tab). The list will be empty
384+
if the Code Snippets Database has not been installed.
383385

384386

385387
================================================================================

0 commit comments

Comments
 (0)