update website for new infrastructure

main
adam j hartz 1 month ago
parent 74b9d7e171
commit 2958c3345f
Signed by: hz
GPG Key ID: 5FDD2840E179AD62

Binary file not shown.

After

Width:  |  Height:  |  Size: 19 KiB

@ -1,41 +1,37 @@
<div style="text-align:center; width:100%;" margin-top:0px;>
<pre style="font-weight:bold;line-height:1.1;background-color:transparent;border-color:transparent;font-size:16pt;text-align:left;display:inline-block; margin-top:0px;">
\
/ /\__/\
\__=( o_O )=
(__________)
|_ |_ |_ |_
</pre>
</div>
<center>
<img src="CURRENT/cat_soup_sketch.png" width=200 />
</center>
<center>
<a class="btn btn-catsoop" href="COURSE/docs">Documentation</a>
<a class="btn btn-catsoop" href="/community/">Community Forum</a>
<a class="btn btn-catsoop" href="/git/catsoop">Code</a>
<a class="btn btn-catsoop" href="/git/catsoop/catsoop/issues">Bug Tracker</a>
</center>
## WHAT IS IT?
CAT-SOOP is a flexible, programmable learning management system based on the
Python programming language. It was originally developed primarily for use in
Python programming language, originally developed primarily for use in
MIT's 6.01 (_Introduction to Electrical Engineering and Computer Science via
Robotics_), and it has since been used in several courses at MIT. Read more
about CAT-SOOP at [this page](COURSE/docs/about).
Robotics_). Although <b>C</b>AT-SOOP was originally designed as an
<b>A</b>utomatic <b>T</b>utor for <b>S</b>ix-<b>O</b>h-<b>O</b>ne
<b>P</b>roblems, it has since been used in several other courses at MIT, and a
few elsewhere. Read more about CAT-SOOP at [this page](COURSE/docs/about).
**Information:**
* Web Site:
* <https://catsoop.mit.edu>
* Tor onion service: <http://wjglyvalrulqaelaptda3pni6lcap46exxsnbiijocrk2guz3nr7dxqd.onion>
* <https://catsoop.org>
* Mailing Lists:
* `catsoop-users@mit.edu`, low-volume list for announcements and discussion (subscribe [here](http://mailman.mit.edu/mailman/listinfo/catsoop-users))
* `catsoop-dev@mit.edu` for development-related discussion (subscribe [here](http://mailman.mit.edu/mailman/listinfo/catsoop-dev))
* Code:
* Git repository: `@{TOR_STRING('git')} clone git://@{cs_url_root.split('/', 2)[-1]}/catsoop.git`
* Repository Web Access: <@{cs_url_root}/cgit/catsoop.git>
* Git Repository: `git clone git://catsoop.org/catsoop.git`
* Repository Web Access: <https://catsoop.org/git/catsoop>
## CAN I USE IT FOR MY COURSE?
@ -47,9 +43,8 @@ terms of the [GNU Affero General Public License, version
the CAT-SOOP system itself, but not to any course material hosted on a CAT-SOOP
instance, unless explicitly stated otherwise.
Although the [documentation](COURSE/docs) is quite sparse, I am working on
it! In the meantime, please feel free to ask questions on the [community
forum](/community).
Although the [documentation](COURSE/docs) is quite sparse, I am working on it!
In the meantime, please feel free to ask questions via the mailing lists.
## IS IT ANY GOOD?

@ -81,10 +81,11 @@ if not broke:
try:
lines, start = inspect.getsourcelines(x)
l = ', <a href="%s/%s.py#n%s" target="_blank">lines %s-%s</a>' % (
l = ', <a href="%s/%s.py#L%s-L%s" target="_blank">lines %s-%s</a>' % (
source_view_url_root,
module.__name__.replace(".", "/"),
start,
start + len(lines) - 1,
start,
start + len(lines) - 1,
)

@ -1,4 +1,4 @@
cs_long_name = "API"
cs_title = cs_content_header = "CAT-SOOP API"
source_view_url_root = "%s/cgit/catsoop.git/tree" % cs_url_root
source_view_url_root = "https://catsoop.org/git/catsoop/catsoop/src/branch/main"

@ -2,23 +2,13 @@
cs_content_header = "CAT-SOOP Documentation (v%s)" % ('.'.join(i.lstrip('0') for i in cs_version.split('.')[:2]))
</python>
<center>
<pre style="border-color:transparent; font-weight:bold; background-color:transparent;font-size:110%; color:inherit; line-height:1.1;display:inline-block;text-align:left;">
\
/ /\__/\
\__=( o_O )=
(__________)
|_ |_ |_ |_
</pre>
</center>
!!! error: A Word of Warning
These docs are extremely sparse right now, and unfortunately, I have
trouble finding the time to sit down and write documentation.
If you have questions about using the software that aren't answered here,
please post them to the [community forum](/community); I'm happy to answer
please e-mail them to the `catsoop-users@mit.edu` mailing list; I'm happy to answer
questions, and I'll also try to work the result into the docs.
Better yet, if you have used CAT-SOOP and are interested in contributing

@ -6,46 +6,46 @@ It's always exciting to receive contributions that help improve CAT-SOOP, so
thank you!
It's also worth mentioning that contributing to CAT-SOOP does not necessarily
mean writing code; there are lots of other ways to help out, too! The easiest
mean writing code; there are lots of other ways to help out, too. The easiest
and best way to contribute to CAT-SOOP is to use it, to report any issues you
find, and to tell your friends/colleagues if you like it! Please see below for
some guidelines about contributing more directly to CAT-SOOP, and please don't
hesitate to reach out if you have questions.
find, and to tell your friends/colleagues if you like it!
In general, we use the [community forum](/community) to develop conversations
around ideas and to help to turn those ideas into actions. Everyone is welcome
to contribute to that process.
But please see below for some guidelines about contributing more directly to
CAT-SOOP, and please don't hesitate to reach out if you have questions.
In general, we use the two mailing lists, `catsoop-users@mit.edu` and
`catsoop-dev@mit.edu` to develop conversations around ideas and to help to turn
those ideas into actions. Everyone is welcome to contribute to that process.
### Do you have a question about using CAT-SOOP, or a request for a new feature?
We're happy to help! The best way to get help is to make a new post on the
[community forum](/community). If you wish to do so without creating an
account on the forum, you can send an e-mail to `community@catsoop.mit.edu`.
We're happy to help! The best way to get help is to send a message to
`catsoop-users@mit.edu`.
### Did you find a bug?
As with most other things, the best place to report issues is the [community
forum](/community), with the exception of security issues (see below). When
reporting a bug, please be as descriptive as you can, and please try to include
an example that demonstrates the issue if possible. Among other things, it is
helpful to know what version of catsoop you're running, what you were trying to
do, and the precise nature of the failure mode (including error messages, if
any).
With the exception of security issues (see below), there are two main ways to
submit bug reports or feature requests: using the [issue tracker](https://catsoop.org/git/catsoop/catsoop/issues)
directly, or sending a message to `catsoop-dev@mit.edu`.
When reporting a bug, please be as descriptive as you can, and please try to
include an example that demonstrates the issue if possible. Among other
things, it is helpful to know what version of catsoop you're running, what you
were trying to do, and the precise nature of the failure mode (including error
messages, if any).
!!! error: Responsible Disclosure of Security Issues
In order to help minimize the effect of security issues, **if you have found a security vulnerability, we ask that you please do not post about it
publicly until we have had a reasonable amount of time to fix the issue.**
Instead, please send e-mail directly to Adam at `hz@mit.edu`,
optionally encrypting your message with [his public
key](https://hz.mit.edu/hz_pubkey.asc). Alternatively, feel free to [send Adam
a private message via the community forum](/community/new-message?username=hz).
key](https://hz.mit.edu/hz_pubkey.asc).
### Are you interested in contributing code?
If you are interested in contributing _code_ to catsoop (to fix a bug or
implement a new feature, for example), a good place to start is to suggest your
change via the [community forum](/community), and to read through the [hacker's
change via the `catsoop-dev@mit.edu` mailing list, and to read through the [hacker's
guide](CURRENT/hacking) for information on the process for contributing code,
as well as information about coding style, tests, etc.
@ -56,5 +56,5 @@ Contributions to documentation are especially appreciated!
If you are comfortable doing so, the best way to submit documentation changes
is by the same process used for code, as described in the [hacker's
guide](CURRENT/hacking). But documentation changes in any format are more than
welcome! Feel free just to post your changes/suggestions (in any format) to
the [community forum](/community) (or e-mail to `community@catsoop.mit.edu`).
welcome! Feel free just to mail your changes/suggestions (in any format) to
the `catsoop-dev@catsoop.mit.edu`).

@ -4,38 +4,30 @@ cs_content_header = "CAT-SOOP Hacker's Guide"
Welcome to the CAT-SOOP hacker's guide! This page is aimed primarily at people
who are interested in helping to continue to evolve CAT-SOOP as a platform in a
direct way, by working on the code of CAT-SOOP itself. It is intended to give
you a brief overview of the CAT-SOOP codebase and surrounding infrastructure,
as well as the process for setting up a local testing copy and for contributing
changes back to CAT-SOOP.
direct way, by working on the code of CAT-SOOP itself (or the associated
documentation). This page is intended to give you a brief overview of the
CAT-SOOP codebase and surrounding infrastructure, as well as the process for
setting up a local testing copy and for contributing changes back to CAT-SOOP.
<tableofcontents/>
<section>Getting Set Up</section>
If you intend to make changes that you will eventually push upstream, a good
first step is to make sure you have an account on the [community
forum](/community), which is the main place where catsoop-related discussion
happens. In general, it is a good idea to make a post there describing the
changes you plan to make (or if there is already a forum thread about it, to
indicate your interest in a post to that thread).
While the forum is used for general questions, the `catsoop-dev@mit.edu`
mailing list is used to coordinate development. You should also consider
making an account for yourself on the [bug tracker](/bugs/), which is where
development is coordinated.
first step is to make yourself an account on the [CAT-SOOP Gitea
Instance](/git/catsoop/catsoop), which is the main hub for CAT-SOOP development
and discussion. You should also add an SSH public key to your account.
<subsection>Cloning the Repository</subsection>
When it is time to go ahead and make your change(s) to the code, it will be
important to have a local copy of the code, by cloning the
[Git](https://git-scm.com/) repository:
After you have set up an account on the Gitea instance and added an SSH key,
you should be able to clone the [main repository](/git/catsoop/catsoop):
```nohighlight
@{TOR_STRING('git')} clone git://@{cs_url_root.split('/', 2)[-1]}/catsoop.git
$ git clone git@catsoop.org:catsoop/catsoop
```
<subsection>Installing CAT-SOOP</subsection>
<subsection>Installing CAT-SOOP for Development</subsection>
The recommended setup for CAT-SOOP involves setting up a development
environment inside of a Python "virtual environment," which can be created with
@ -85,7 +77,7 @@ clone the sample course if you do not already have another course to work with,
using the following command:
```nohighlight
@{TOR_STRING('git')} clone git://@{cs_url_root.split('/', 2)[-1]}/sample_course.git ~/.local/share/catsoop/courses/sample_course
git clone git@catsoop.org:catsoop/sample_course ~/.local/share/catsoop/courses/sample_course
```
@ -105,8 +97,8 @@ process and restarting it.
If you don't already have an idea in mind, some issues in the issue tracker are
marked as potential good opportunities for a first dive into the codebase. You
can view these issues [here](/bugs/view_all_bug_page.php?filter=6042230d31597),
or by manually searching for them from the catsoop issue tracker, and feel free
can view these issues [here](https://catsoop.org/git/catsoop/catsoop/issues?q=&type=all&state=open&labels=17&milestone=0&assignee=0&poster=0),
or by manually searching for them from the catsoop issue tracker. Feel free
to reach out if you need help!
<section>Rules to Write/Commit By</section>
@ -118,12 +110,13 @@ to reach out if you need help!
priority.
1. All substantial new public-facing functions should have docstrings. These
docstrings should be formatted using CAT-SOOP Markdown, as the [API
docstrings should be formatted using CAT-SOOP Markdown since the [API
Documentation](COURSE/docs/api) is automatically generated from them. In
cases of adding new functionality or changing existing functionality, the
documentation should also be updated where appropriate.
cases of adding new functionality or changing existing functionality, this
website (Git repo [here](/git/catsoop/website)) should also be updated
where appropriate.
1. Substantial new functionality should have associated unit tests where
1. Substantial new functionality should have associated tests where
appropriate. Code related to user interaction / user interface is
difficult to test, but it should still be tested where it's feasible to do
so.
@ -133,7 +126,8 @@ to reach out if you need help!
1. To ensure consistency across the codebase, CAT-SOOP uses the
<a href="https://black.readthedocs.io/en/stable/" target="_blank">black</a>
code formatting tool. Please run your changes through `black`.
code formatting tool. Please run your changes through `black` before
submitting them.
1. Logically separate changes should have separate commits in the repository.
@ -173,43 +167,24 @@ Before sending your changes, please:
1. Add an appropriate entry to `CHANGELOG`, and, if you wish, add your name
to the `CONTRIBUTORS` file.
<subsection>Preparing and Sending Patches</subsection>
In general, we follow a patch-based contribution model, coordinated via the
`catsoop-dev@mit.edu` mailing list and the [bug tracker](/bugs/). The next
step in that process, after making your changes and committing them locally, is
to prepare patches to be shared with us.
!!! note: Note
If you are having trouble generating your patch files, or if you have other
questions about the process, please reach out via the mailing lists, and we'd
be happy to help!
There are a few different ways that we'll accept patches.
<subsection>Sending Changes</subsection>
1. For small patches, you can use the `git send-email` command to send your
patches via email. There is a nice tutorial about this approach at
<https://git-send-email.io/>. Please make sure to send patches to
`catsoop-dev@mit.edu`.
We're not terribly picky about how your changes reach us, so there are at least
two options:
1. You can instead use `git format-patch`.
If you are using Bash, then the following command, for example, will
generate a patch file containing all of the commits not present in the base
repo:
1. You can use Gitea's "fork" functionality to create a copy of the catsoop
repository under your own username in Gitea and then use Gitea's "pull
request" feature. In order to start the process, you should push your
changes to a new branch on your fork of the main repository. When pushing,
you should see a link for creating a new pull request. You can follow this
link, fill out a little bit of information about the changes, and submit
your pull request.
```nohighlight
git format-patch "$(git merge-base dev `git branch --show-current`)" --stdout > NAME.patch
```
You can then attach the patch to an e-mail to `catsoop-dev@mit.edu` (or, if
you prefer, as an attachment in the forum or the bug tracker).
3. Alternatively, if your copy of the repository is accessible over a network
connection (for example, on a public source forge like Gitlab, or in a
publicly-accessible directory on Athena), it is fine to send a pointer to that
repository instead of sending patches (you could use `git request-pull` or
any other mechanism).
1. You can send patches via e-mail (by using `git-send-email` or
`git-request-pull`, or by attaching the output from `git format-patch`)
to `catsoop-dev@mit.edu`.
Roughly speaking, any way you want to get your changes to us is fine!
<subsection>Feedback</subsection>
@ -223,51 +198,3 @@ one of the following flavors:
If you don't hear back right away, feel free to send a follow-up message. And
in any case, feel free to continue the conversation, to make changes, etc.
<section>Versioning and Releases</section>
Typically, CAT-SOOP development is very "bursty," with most development
happening during the summer months and January (in between academic terms), and
relatively little development happening during the semesters.
In general, the goal is to release a new version of CAT-SOOP once every
semester. As MIT's semesters start in September and February, respectively,
this means a new major version just before the start of each semester.
Releases are versioned by date, with version `20YY.9` referring to the
September release, and `20YY.2` referring to the February release.
Beyond this, additional "minor" version numbers may also be used, usually for
bug fixes. In general, version `20YY.M.V` refers to the `V`<sup>th</sup>
release of version `20YY.M`. We start counting `V` from `0`, so the initial
release of each major version is `20YY.M.0`. Unlike major version bumps, these
minor versions will not happen on a fixed schedule, but, rather, will be
released as necessary, or as interesting new features are added.
Most major versions will only be supported for one semester (until the next
version's release) and may contain backwards-incompatible changes, but,
starting with `2019.9`, the September releases in odd-numbered years will be
tagged as **long-term support** (LTS) releases and will continue to be
supported for two full years. These versions will receive no
backwards-incompatible changes during that time (except in the case where such
a change is necessary for security reasons).
Each new release (including minor releases) will be accompanied by a post to
the community forum, which will include information about what changed from the
previous version, as well as an indication of steps that need to be taken when
upgrading.
<subsection>Repository Structure</subsection>
All development happens on the `dev` branch in the Git repository.
Each version of catsoop has a separate branch in the repository, named like
`v20YY.M` (for regular versions) or `v20YY.M-lts` (for LTS versions), where
bugfixes and other changes are backported from the `dev` branch. Generally,
new features and bugfixes only make their way into release branches by way of
backporting changes from `dev`; that is to say, changes should always happen on
`dev` first, except in rare cases.
Each release is tagged with a version number `v20YY.M.V`. Additionally, the
current release and the current LTS release are tagged with `current_release`
and `current_lts`, respectively. These tagged releases are also signed with
[Adam's PGP key](https://hz.mit.edu/hz_pubkey.asc).

@ -27,7 +27,5 @@ cs_top_menu = [
todo = """!!! warning: This Page Needs Attention
Contributions to documentation are more than welcome!
You can post suggestions, questions, or other feedback to the <a
href="/community" target="_blank">community forum</a>. If you don't want
to create an account there, you can post by sending e-mail to
`community@catsoop.mit.edu`."""
You can e-mail suggestions, questions, or other feedback to `catsoop-users@mit.edu`.
"""

@ -1,9 +1,10 @@
cs_auth_required = False
cs_long_name = "CAT-SOOP"
cs_content_header = ""
TOR_STRING = lambda n: ("torsocks %s" % n) if "onion" in cs_url_root else n
source_link = "%s/cgit/website.git" % cs_url_root
source_link = "%s/git/catsoop/website" % cs_url_root
cs_footer = """The content of this page is Copyright &copy; 2016-2022 by the CAT-SOOP Developers.<br/>
This content is licensed under the <a href="BASE/_util/license" target="_blank">GNU Affero General Public License, version 3</a>, as is CAT-SOOP itself.<br/>

Loading…
Cancel
Save