diff options
Diffstat (limited to 'site/contrib.md')
-rw-r--r-- | site/contrib.md | 122 |
1 files changed, 122 insertions, 0 deletions
diff --git a/site/contrib.md b/site/contrib.md new file mode 100644 index 0000000..5e911fd --- /dev/null +++ b/site/contrib.md | |||
@@ -0,0 +1,122 @@ | |||
1 | --- | ||
2 | title: Information about sending patches for review | ||
3 | x-toc-enable: true | ||
4 | ... | ||
5 | |||
6 | Download TransChat from the Git repository like so: | ||
7 | |||
8 | git clone https://notabug.org/transchat/trans.chat.git | ||
9 | |||
10 | Git is a version control system, used to host the site, to coordinate | ||
11 | development. You can download and work on the entire website, using Git. | ||
12 | |||
13 | The Git software is available on Windows, MacOS, GNU+Linux, BSD and others. We | ||
14 | strongly recommend GNU+Linux or BSD, but Windows and Mac OS also work with | ||
15 | Git. Search on Google for basic information about how to use Git. | ||
16 | |||
17 | Some of the instructions here assume that you use GNU+Linux or BSD, so you will | ||
18 | have to adapt accordingly if you use something else. The core administrators | ||
19 | maintaining the website all use GNU+Linux. | ||
20 | |||
21 | You can submit your patches via | ||
22 | [Notabug pull requests](#how-to-submit-your-patches-via-pull-requests) or | ||
23 | |||
24 | Editing the website and documentation, wiki-style | ||
25 | ------------------------------------------------- | ||
26 | |||
27 | The website and documentation is inside the `www` directory in the | ||
28 | [Git repository](#how-to-download-transchat-from-the-git-repository), in | ||
29 | Pandoc flavoured Markdown. The website is generated into static HTML via Pandoc | ||
30 | with the following scripts in that directory: | ||
31 | |||
32 | - index.sh: generates the news feed (on the News section of the website) | ||
33 | - publish.sh: converts an .md file to an .html file | ||
34 | - Makefile: with calls to index.sh and publish.sh, compiles the entire | ||
35 | TransChat website | ||
36 | |||
37 | Use any standard text editor (e.g. Vim, Emacs, Nano, Gedit) to edit the files, | ||
38 | commit the changes and | ||
39 | [send patches](#how-to-submit-your-patches-via-pull-requests). | ||
40 | |||
41 | Optionally, you can install a web server (e.g. lighttpd, nginx) locally and | ||
42 | set the document root to the *www* directory in your local Git repository. | ||
43 | With this configuration, you can then generate your local version of the | ||
44 | website and view it by typing `localhost` in your browser's URL bar. | ||
45 | |||
46 | Privacy of contributors (you do not have to reveal your name or identity!) | ||
47 | ------------------------------------------------------------------------- | ||
48 | |||
49 | Contributions that you make are publicly recorded, in a Git repository which | ||
50 | everyone can access. This includes the name and email address of the | ||
51 | contributor. | ||
52 | |||
53 | In Git, for author name and email address, you do not have to use identifying | ||
54 | data. You can use TransChat Contributor and your email address could be | ||
55 | specified as contributor@transchat.org.uk. You are permitted to do this, if | ||
56 | you wish to maintain privacy. | ||
57 | |||
58 | Of course, you can use whichever name you like. | ||
59 | |||
60 | Legally speaking, all copyright is automatic under the Berne Convention of | ||
61 | international copyright law. It does not matter which name, or indeed whether | ||
62 | you even declare a copyright (but we do require that certain copyright | ||
63 | licenses are used - read more about that on this same page). | ||
64 | |||
65 | If you use a different name and email address on your commits/patches, then | ||
66 | you should be fairly anonymous. | ||
67 | |||
68 | General guidelines for submitting patches | ||
69 | ----------------------------------------- | ||
70 | |||
71 | We require all patches to be submitted under a free license: | ||
72 | <https://www.gnu.org/licenses/license-list.html>. | ||
73 | |||
74 | - For documentation, we require GNU Free Documentation License v1.3 or higher. Basically, this is required on any Web pages that you contribute, or make changes to. | ||
75 | - GNU General Public License v3 is highly recommended, if you're contributing code (e.g. working on the static site generator that the site uses) | ||
76 | |||
77 | If you do not agree to use one of these licenses accordingly, your contribution will be rejected. | ||
78 | |||
79 | *Always* declare a license on your work! Not declaring a license means that | ||
80 | the default, restrictive copyright laws apply, which would make your work | ||
81 | non-free. | ||
82 | |||
83 | GNU+Linux is generally recommended as the OS of choice, for TransChat | ||
84 | development. | ||
85 | |||
86 | General code review guidelines | ||
87 | ------------------------------ | ||
88 | |||
89 | Any member of the public can | ||
90 | [submit a patch](#how-to-submit-your-patches-via-pull-requests). | ||
91 | |||
92 | Your patch will be reviewed for quality assurance, and merged if accepted. | ||
93 | |||
94 | How to download TransChat from the Git repository | ||
95 | ------------------------------------------------- | ||
96 | |||
97 | In your terminal: | ||
98 | |||
99 | git clone https://notabug.org/transchat/trans.chat.git | ||
100 | |||
101 | A new directory named `transchat` will have been created, containing | ||
102 | transchat. | ||
103 | |||
104 | How to submit your patches (via pull requests) | ||
105 | ---------------------------------------------- | ||
106 | |||
107 | Make an account on <https://notabug.org/> and navigate (while logged in) to | ||
108 | <https://notabug.org/transchat/trans.chat>. Click *Fork* and in your account, | ||
109 | you will have your own repository of TransChat. Clone your repository, make | ||
110 | whatever changes you like to it and then push to your repository, in your | ||
111 | account on NotABug. | ||
112 | |||
113 | Now, navigate to <https://notabug.org/transchat/trans.chat/pulls> and click | ||
114 | *New Pull Request*. | ||
115 | |||
116 | You can submit your patches there. Alternative, you can log onto the TransChat | ||
117 | IRC channel and notify the channel of which patches you want reviewed, if you | ||
118 | have your own Git repository with the patches. | ||
119 | |||
120 | Once you have issued a Pull Request, the TransChat maintainers will be notified | ||
121 | via email. If you do not receive a fast enough response from the project, then | ||
122 | you could also notify the project via the `#transchat` channel on Libera. | ||