Mercurial > web-octave
annotate README.md @ 279:54532ba03391
Redirect and merge /bugs to /support page.
* pages/bugs.md: make redirect to /support.
* pages/menu/support.md: merge content of pages/menu/bugs.md.
* pages/menu/bugs.md: delete page.
author | Kai T. Ohlhus <k.ohlhus@gmail.com> |
---|---|
date | Sun, 08 May 2022 02:29:31 +0900 |
parents | 87b849399b9f |
children |
rev | line source |
---|---|
119
22f0158e5848
doc: Document rule about categories for posts.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
115
diff
changeset
|
1 # GNU Octave Website development |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
2 |
222 | 3 This is the <https://www.octave.org> website development repository. |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
4 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
5 The development and deployment workflow in short: |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
6 |
222 | 7 1. The website is developed at two synchronized locations: |
8 - <https://hg.octave.org/web-octave> (Mercurial) | |
9 - <https://github.com/gnu-octave/gnu-octave.github.io> (Git) | |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
10 |
222 | 11 2. Static HTML pages are generated from these repositories |
12 and deployed at | |
13 - <https://web.cvs.savannah.gnu.org/viewvc/octave/?root=octave> (Savannah) | |
14 - <https://gnu-octave.github.io/> (GitHub Pages) | |
15 | |
16 3. The deployment to GitHub Pages happens automatically by pushing to the | |
17 respective repository. The deployment on Savannah is more complicated and | |
18 described below in detail and is visible at <https://www.octave.org> that | |
19 redirects to <https://www.gnu.org/software/octave>. | |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
20 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
21 |
222 | 22 ## Simple website changes / contributions |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
23 |
211
a3ad764ca547
* README.md: Update developer description.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
183
diff
changeset
|
24 Anyone is free to clone this website development repository, simply type |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
25 |
222 | 26 git clone https://github.com/gnu-octave/gnu-octave.github.io.git |
27 hg clone https://hg.octave.org/web-octave | |
31
beb4387a8937
Create README.md
Alex Krolick <whokilledtheelectricmonk@gmail.com>
parents:
diff
changeset
|
28 |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
29 to get anonymous read access without writing privileges. |
222 | 30 |
31 If you want submit changes/additions, please create a | |
32 [**pull request**](https://docs.github.com/en/github/getting-started-with-github/github-glossary#pull-request) | |
33 on GitHub or contact the Octave developers at <https://octave.discourse.group/>. | |
34 | |
35 > **Note:** Changes made to the GitHub page repository are only visible there. | |
36 > To change <https://www.octave.org>, the Savannah CVS repository must be | |
37 > updated (see below). | |
38 | |
39 | |
40 ### Add a new RSS post | |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
41 |
222 | 42 Duplicate another post in the subdirectory `_posts` and adjust the filename, |
43 especially the date. | |
44 | |
45 **Be sure to choose the correct categories!!** | |
46 | |
47 `categories: news release` is reserved for release announcements, those posts | |
48 are also displayed inside the Octave GUI. Consider choosing another category | |
49 like `categories: news` or alike for less important news. | |
50 | |
51 | |
52 ## Advanced development | |
53 | |
54 ### Synchronize Mercurial and GitHub repositories | |
55 | |
56 You need writing permissions to the Mercurial repository | |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
57 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
58 hg clone ssh://gnuoctave@octave.org/hg/web-octave |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
59 |
222 | 60 Add to `.hg/hgrc` |
61 | |
62 [paths] | |
63 default = ssh://gnuoctave@hg-new.octave.org/hg/web-octave | |
64 github = git+ssh://git@github.com:gnu-octave/gnu-octave.github.io.git | |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
65 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
66 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
67 ### Building requisites |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
68 |
222 | 69 To build the static website offline, you need to install [Ruby][] and |
70 [Bundler][]. For Debian/Ubuntu please perform the following setup fist. | |
71 For other Linux distributions this command might change. | |
182
7a664b44fd8d
Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
156
diff
changeset
|
72 |
7a664b44fd8d
Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
156
diff
changeset
|
73 sudo apt-get install ruby-full build-essential zlib1g-dev |
7a664b44fd8d
Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
156
diff
changeset
|
74 |
183
ff5b4e46fe3d
Update build information.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
182
diff
changeset
|
75 gem install bundler |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
76 |
183
ff5b4e46fe3d
Update build information.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
182
diff
changeset
|
77 From now on, everything is handled by Bundler. Install all required |
182
7a664b44fd8d
Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
156
diff
changeset
|
78 dependencies for the static Octave website by running |
126
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
79 |
182
7a664b44fd8d
Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
156
diff
changeset
|
80 bundle install |
7a664b44fd8d
Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
156
diff
changeset
|
81 |
222 | 82 from within the checked-out website development repository (Mercurial or |
83 GitHub). | |
126
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
84 |
222 | 85 For the responsive webpages, we internally use the [Foundation 6][Foundation] |
86 framework. All necessary files are already included inside this website | |
87 development repository. | |
101
6271c701830d
Document the usage of the foundation 5 framework.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
96
diff
changeset
|
88 |
222 | 89 [Ruby]: https://www.ruby-lang.org/ |
90 [Bundler]: https://bundler.io/ | |
91 [Foundation]: https://get.foundation/sites/docs/ | |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
92 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
93 |
222 | 94 ### Building the static website offline |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
95 |
183
ff5b4e46fe3d
Update build information.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
182
diff
changeset
|
96 All relevant information for Bundler to build the static website are located in |
ff5b4e46fe3d
Update build information.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
182
diff
changeset
|
97 the files `_config.yml`, `Gemfile`, and `Gemfile.lock`. Typing |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
98 |
182
7a664b44fd8d
Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
156
diff
changeset
|
99 bundle exec jekyll build |
31
beb4387a8937
Create README.md
Alex Krolick <whokilledtheelectricmonk@gmail.com>
parents:
diff
changeset
|
100 |
211
a3ad764ca547
* README.md: Update developer description.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
183
diff
changeset
|
101 from the repository root directory will build a complete static website |
a3ad764ca547
* README.md: Update developer description.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
183
diff
changeset
|
102 into the subdirectory `_site` using this information. This directory is |
a3ad764ca547
* README.md: Update developer description.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
183
diff
changeset
|
103 ignored by Mercurial and will be created on first build. |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
104 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
105 Especially for development, it is beneficial to watch the changes locally |
182
7a664b44fd8d
Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
156
diff
changeset
|
106 before pushing any changes. Jekyll provides a local webserver by typing |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
107 |
182
7a664b44fd8d
Use Bundler for consistent development environment with Jekyll.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
156
diff
changeset
|
108 bundle exec jekyll serve |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
109 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
110 and rebuilds the whole static website automatically, as it monitors any |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
111 file changes. |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
112 |
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
113 |
222 | 114 ### Deploying the static website online at Savannah CVS |
119
22f0158e5848
doc: Document rule about categories for posts.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
115
diff
changeset
|
115 |
222 | 116 For this step you need to have writing permissions to the Savannah CVS |
126
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
117 repository. Usually, it should suffice to type |
31
beb4387a8937
Create README.md
Alex Krolick <whokilledtheelectricmonk@gmail.com>
parents:
diff
changeset
|
118 |
126
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
119 make deploy |
94
e8fc61e077fc
Merged closed branch "kai" into default.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
31
diff
changeset
|
120 |
126
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
121 if anything doesn't work as expected, look at the provided `Makefile` and |
d851f4f89fb4
Improve Makefile deployment mechanism.
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
119
diff
changeset
|
122 perform the steps on your own manually, if necessary. |
272
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
123 |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
124 |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
125 ## License |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
126 |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
127 ### Website Design and Code |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
128 |
273 | 129 - Copyright (c) 2016-2022 The Octave Project Developers. |
130 - Copyright (c) 2015-2016 Alex Krolick. | |
272
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
131 |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
132 See the file LICENSE in the top-level directory of this distribution or |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
133 <https://octave.org/copyright/>. |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
134 |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
135 The Octave website is free software: you can redistribute it and/or modify |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
136 it under the terms of the GNU General Public License as published by the |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
137 Free Software Foundation, either version 3 of the License, or (at your option) |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
138 any later version. |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
139 |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
140 The Octave website is distributed in the hope that it will be useful, but |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
141 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
142 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
143 for more details. |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
144 |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
145 You should have received a copy of the GNU General Public License |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
146 along with the Octave website; see the file COPYING. If not, see |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
147 <https://www.gnu.org/licenses/>. |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
148 |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
149 ### Website Content |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
150 |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
151 The website content is licensed under a |
c90fdd9f5b86
README.md: Clarify LICENSE of code and content (closes #1).
Kai T. Ohlhus <k.ohlhus@gmail.com>
parents:
222
diff
changeset
|
152 [Creative Commons Attribution-NoDerivatives 4.0 International License](https://creativecommons.org/licenses/by-nd/4.0/). |