Skip to content
This repository has been archived by the owner on Apr 26, 2024. It is now read-only.

Removed page summaries from the top of installation and contributing doc pages #10711

Merged
merged 5 commits into from
Aug 27, 2021
Merged

Removed page summaries from the top of installation and contributing doc pages #10711

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
33c3e6b
Removed page summaries, fixed some links, fixed ToC being overlapped
Aug 27, 2021
39edd70
Added changelog
Aug 27, 2021
acf7a63
Altered changelog as suggested in code review
Aug 27, 2021
2ef5150
Applied suggestions from code review
Aug 27, 2021
f2c03ef
Update 10711.doc with suggestion from code review
Azrenbeth Aug 27, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 12 additions & 34 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,30 +2,6 @@ Welcome to Synapse

This document aims to get you started with contributing to this repo!

- [1. Who can contribute to Synapse?](#1-who-can-contribute-to-synapse)
- [2. What do I need?](#2-what-do-i-need)
- [3. Get the source.](#3-get-the-source)
- [4. Install the dependencies](#4-install-the-dependencies)
* [Under Unix (macOS, Linux, BSD, ...)](#under-unix-macos-linux-bsd-)
* [Under Windows](#under-windows)
- [5. Get in touch.](#5-get-in-touch)
- [6. Pick an issue.](#6-pick-an-issue)
- [7. Turn coffee and documentation into code and documentation!](#7-turn-coffee-and-documentation-into-code-and-documentation)
- [8. Test, test, test!](#8-test-test-test)
* [Run the linters.](#run-the-linters)
* [Run the unit tests.](#run-the-unit-tests-twisted-trial)
* [Run the integration tests (SyTest).](#run-the-integration-tests-sytest)
* [Run the integration tests (Complement).](#run-the-integration-tests-complement)
- [9. Submit your patch.](#9-submit-your-patch)
* [Changelog](#changelog)
+ [How do I know what to call the changelog file before I create the PR?](#how-do-i-know-what-to-call-the-changelog-file-before-i-create-the-pr)
+ [Debian changelog](#debian-changelog)
* [Sign off](#sign-off)
- [10. Turn feedback into better code.](#10-turn-feedback-into-better-code)
- [11. Find a new issue.](#11-find-a-new-issue)
- [Notes for maintainers on merging PRs etc](#notes-for-maintainers-on-merging-prs-etc)
- [Conclusion](#conclusion)

# 1. Who can contribute to Synapse?

Everyone is welcome to contribute code to [matrix.org
Expand All @@ -35,7 +11,7 @@ follow a simple 'inbound=outbound' model for contributions: the act of
submitting an 'inbound' contribution means that the contributor agrees to
license the code under the same terms as the project's overall 'outbound'
license - in our case, this is almost always Apache Software License v2 (see
[LICENSE](LICENSE)).
[LICENSE](https://github.com/matrix-org/synapse/blob/develop/LICENSE)).

# 2. What do I need?

Expand Down Expand Up @@ -98,17 +74,19 @@ to work on.

# 7. Turn coffee and documentation into code and documentation!

Synapse's code style is documented [here](docs/code_style.md). Please follow
Synapse's code style is documented [here](../code_style.md). Please follow
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aha, we have a fun mismatch here where either the links work on the documentation website, or they work on github, but not both.

This is due to us importing this document, rather than it actually living in the docs/ folder.

A simple fix for this is just to link directly to the documentation website here for now. Otherwise we should probably just move this document to docs/development/contributing_guide.md and just put a link to that file in CONTRIBUTING.md instead.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh I didn't think about it breaking it when looking on github...

Why is CONTRIBUTING.md inside of the development folder (and similarly why must it also NOT be in the development folder)?

There seems to be other files that are under the development subsection on the contents page but are just in docs/ (e.g. log_contexts.md) is there a reason we can't just do that with CONTRIBUTING?

(or all the files like log_contexts.md in the wrong place atm)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Github sees the file at CONTRIBUTING.md and points to it in various places around the codebase (such as when submitting a PR for the first time). Additionally, it's probably been linked in several places. As such it's a good place for it.

But we could easily just put a file there which contains a link to a file in docs/, like we did with INSTALL.md.

We should probably do all this in a separate PR though.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There seems to be other files that are under the development subsection on the contents page but are just in docs/ (e.g. log_contexts.md) is there a reason we can't just do that with CONTRIBUTING?

Ah yes, this was to prevent breaking links to these files that existed before the docs website. It would be nice to move them at some point, I agree, as it does cause confusion.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ahh ok, so for now I'll remove all of those changes then open a seperate PR to do something like was done for INSTALL.md

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good, yep!

it, including the conventions for the [sample configuration
file](docs/code_style.md#configuration-file-format).
file](../code_style.md#configuration-file-format).

There is a growing amount of documentation located in the [docs](docs)
There is a growing amount of documentation located in the
[docs](https://github.com/matrix-org/synapse/tree/develop/docs)
directory. This documentation is intended primarily for sysadmins running their
own Synapse instance, as well as developers interacting externally with
Synapse. [docs/dev](docs/dev) exists primarily to house documentation for
Synapse developers. [docs/admin_api](docs/admin_api) houses documentation
regarding Synapse's Admin API, which is used mostly by sysadmins and external
service developers.
own Synapse instance, as well as developers interacting externally with Synapse.
[docs/development](https://github.com/matrix-org/synapse/tree/develop/docs/development)
exists primarily to house documentation for Synapse developers.
[docs/admin_api](https://github.com/matrix-org/synapse/tree/develop/docs/admin_api)
houses documentation regarding Synapse's Admin API, which is used mostly by sysadmins
and external service developers.

If you add new files added to either of these folders, please use [GitHub-Flavoured
Markdown](https://guides.github.com/features/mastering-markdown/).
Expand Down Expand Up @@ -431,7 +409,7 @@ By now, you know the drill!
# Notes for maintainers on merging PRs etc

There are some notes for those with commit access to the project on how we
manage git [here](docs/development/git.md).
manage git [here](git.md).

# Conclusion

Expand Down
1 change: 1 addition & 0 deletions changelog.d/10711.doc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Removed page summaries from top of installation and contributing pages.
Azrenbeth marked this conversation as resolved.
Show resolved Hide resolved
39 changes: 0 additions & 39 deletions docs/setup/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,44 +1,5 @@
# Installation Instructions

There are 3 steps to follow under **Installation Instructions**.

- [Installation Instructions](#installation-instructions)
- [Choosing your server name](#choosing-your-server-name)
- [Installing Synapse](#installing-synapse)
- [Installing from source](#installing-from-source)
- [Platform-specific prerequisites](#platform-specific-prerequisites)
- [Debian/Ubuntu/Raspbian](#debianubunturaspbian)
- [ArchLinux](#archlinux)
- [CentOS/Fedora](#centosfedora)
- [macOS](#macos)
- [OpenSUSE](#opensuse)
- [OpenBSD](#openbsd)
- [Windows](#windows)
- [Prebuilt packages](#prebuilt-packages)
- [Docker images and Ansible playbooks](#docker-images-and-ansible-playbooks)
- [Debian/Ubuntu](#debianubuntu)
- [Matrix.org packages](#matrixorg-packages)
- [Downstream Debian packages](#downstream-debian-packages)
- [Downstream Ubuntu packages](#downstream-ubuntu-packages)
- [Fedora](#fedora)
- [OpenSUSE](#opensuse-1)
- [SUSE Linux Enterprise Server](#suse-linux-enterprise-server)
- [ArchLinux](#archlinux-1)
- [Void Linux](#void-linux)
- [FreeBSD](#freebsd)
- [OpenBSD](#openbsd-1)
- [NixOS](#nixos)
- [Setting up Synapse](#setting-up-synapse)
- [Using PostgreSQL](#using-postgresql)
- [TLS certificates](#tls-certificates)
- [Client Well-Known URI](#client-well-known-uri)
- [Email](#email)
- [Registering a user](#registering-a-user)
- [Setting up a TURN server](#setting-up-a-turn-server)
- [URL previews](#url-previews)
- [Troubleshooting Installation](#troubleshooting-installation)


## Choosing your server name

It is important to choose the name for your server before you install Synapse,
Expand Down
1 change: 1 addition & 0 deletions docs/website_files/table-of-contents.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
main {
position: relative;
margin-left: 100px !important;
margin-right: 250px !important;
Azrenbeth marked this conversation as resolved.
Show resolved Hide resolved
}
.sidetoc {
margin-left: auto;
Expand Down