Merge branch 'contributing-to-devel-docs' into 'main'

Move the scattered .md documents to the devel guide

See merge request GNOME/librsvg!784

8 files changed, 342 insertions, 454 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
deleted file mode 100644
index f0da922a..00000000
--- a/CONTRIBUTING.md
+++ /dev/null
@@ -1,301 +0,0 @@
-Contributing to librsvg
-=======================
-
-Thank you for looking in this file!  There are different ways of
-contributing to librsvg, and we appreciate all of them.
-
-* [Source repository](#source-repository)
-* [Reporting bugs](#reporting-bugs)
-* [Feature requests](#feature-requests)
-* [Hacking on librsvg](#hacking-on-librsvg)
-
-There is a **code of conduct** for contributors to librsvg; please see the
-file [`code-of-conduct.md`][coc].
-
-## Source repository
-
-Librsvg's main source repository is at gitlab.gnome.org.  You can view
-the web interface here:
-
-https://gitlab.gnome.org/GNOME/librsvg
-
-Development happens in the `main` branch.  There are also branches for
-stable releases.
-
-Alternatively, you can use the mirror at Github:
-
-https://github.com/GNOME/librsvg
-
-Note that we don't do bug tracking in the Github mirror; see the next
-section.
-
-If you need to publish a branch, feel free to do it at any
-publically-accessible Git hosting service, although gitlab.gnome.org
-makes things easier for the maintainers of librsvg.
-
-To work on the source code, you may find the "[Hacking on
-librsvg](#hacking-on-librsvg)" section helpful.
-
-## Reporting bugs
-
-Please report bugs at https://gitlab.gnome.org/GNOME/librsvg/issues
-
-If you want to report a rendering bug, or a missing SVG feature,
-please provide an example SVG file as an attachment to your bug
-report.  It really helps if you can minimize the SVG to only the
-elements required to reproduce the bug or see the missing feature, but
-it is not absolutely required.  **Please be careful** of publishing
-SVG images that you don't want other people to see, or images whose
-copyright does not allow redistribution; the bug tracker is a public
-resource and attachments are visible to everyone.
-
-You can also [browse the existing bugs][bugs-browse].
-
-### Obtaining debug logs
-
-Librsvg can be asked to output debug logs.  Set the `RSVG_LOG`
-environment variable, and then librsvg will print some 
-information to stdout:
-
-```
-$ RSVG_LOG=1 some-program-that-uses-librsvg
-... debug output goes here ...
-```
-
-As of librsvg 2.43.5, there are no options you can set in the
-`RSVG_LOG` variable; the library just checks whether that environment
-variable is present or not.
-
-## Feature requests
-
-Librsvg aims to be a small and relatively simple SVG rendering
-library.  Currently we do not plan to support scripting, animation, or
-interactive features like mouse events on SVG elements.
-
-However, we *do* aim go provide good support for SVG's graphical
-features.  Please see the "[reporting bugs](#reporting-bugs)" section for
-information about our bug tracking system; feature requests should be
-directed there.
-
-It is especially helpful if you file bug for a feature request along
-with a sample SVG file.
-
-## Hacking on librsvg
-
-The library's internals are being documented at
-https://gnome.pages.gitlab.gnome.org/librsvg/internals/librsvg/index.html
-
-Please see that documentation for common tasks like adding support for
-a new CSS property.
-
-What can you hack on?
-
-* [Bugs for newcomers](https://gitlab.gnome.org/GNOME/librsvg/-/issues?label_name%5B%5D=4.+Newcomers)
-* Pick something from the [development roadmap](devel-docs/README.md)! FIXME: relink
-
-### Working on the source
-
-Librsvg uses an autotools setup, which is described in detail [in this
-blog post][blog].
-
-If you need to **add a new source file**, you need to do it in the
-toplevel [`Makefile.am`][toplevel-makefile].  *Note that this is for
-both C and Rust sources*, since `make(1)` needs to know when a Rust
-file changed so it can call `cargo` as appropriate.
-
-It is perfectly fine to [ask the maintainer][maintainer] if you have
-questions about the Autotools setup; it's a tricky bit of machinery,
-and we are glad to help.
-
-Please read the file [`ARCHITECTURE.md`][arch]; this describes the
-overall flow of the source code, so hopefully it will be easier for
-you to navigate.
-
-### Taking advantage of Continuous Integration
-
-If you fork librsvg in `gitlab.gnome.org` and push commits to your
-forked version, the Continuous Integration machinery (CI) will run
-automatically.
-
-A little glossary:
-
-* ***Continuous Integration (CI)*** - A tireless robot that builds
-  librsvg on every push, and runs various kinds of tests.
-  
-* ***Pipeline*** - A set of ***jobs*** that may happen on every push.
-  Every pipeline has ***stages*** of things that get run.  You can
-  [view recent
-  pipelines](https://gitlab.gnome.org/GNOME/librsvg/pipelines) and
-  examine their status.
-  
-* ***Stages*** - Each stage runs some kind of test on librsvg, and
-  depends on the previous stages succeeding.  We have a *Test* stage
-  that just builds librsvg as quickly as possible and runs its test
-  suite.  If that succeeds, then it will go to a *Lint* stage which
-  runs `rustfmt` to ensure that the coding style remains consistent.
-  Finally, there is a `Cross_distro` stage that tries to build/test
-  librsvg on various operating systems and configurations.
-  
-* ***Jobs*** - You can think of a job as "something that runs in a
-  specific container image, and emits a success/failure result".  For
-  example, the `Test` stage runs a job in a fast Fedora container.
-  The `Lint` stage runs `rustfmt` in a Rust-specific container that
-  always contains a recent version of `rustfmt`.  Distro-specific jobs
-  run on container images for each distro we support.
-  
-The default CI pipeline for people's branches is set up to build your
-branch and to run the test suite and lints.  If any tests fail, the
-pipeline will fail and you can then examine the job's build
-artifacts.  If the lint stage fails, you will have to reindent your
-code.
-
-***Automating the code formatting:*** You may want to enable a
-[client-side git
-hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) to run
-`rustfmt` before you can commit something; otherwise the `Lint` stage
-of CI pipelines will fail:
-
-1. `cd librsvg`
-
-1. `mv .git/hooks/pre-commit.sample .git/hooks/pre-commit`
-
-1. Edit `.git/hooks/pre-commit` and put in one of the following
-   commands:
-
-  * If you want code reformatted automatically, no questions asked:
-    `cargo fmt`
-    ***Note:*** if this actually reformats your code while committing,
-    you'll have to re-stage the new changes and `git commit --amend`.  Be
-    careful if you had unstaged changes that got reformatted!
-
-  * If you want to examine errors if rustfmt doesn't like your
-    indentation, but don't want it to make changes on its own:  
-    `cargo fmt --all -- --check`
-
-### Test suite
-
-Please make sure that the test suite passes with the changes in your
-branch.  The easiest way to run all the tests is to go to librsvg's
-toplevel directory and run `make check`.  This will run both the small
-unit tests and the black box tests in the `librsvg/tests` directory.
-
-It's possible that a wide swath of tests will fail when you do this,
-don't panic! that's likely just text rendering, which varies a bit
-from distro to distro. To run the test suite on the same OS as the 
-CI, first install docker then see this file 
-[`tools/docker/README.md`][docker-tests-readme].
-
-If you need to add new tests (you should, for new features, or for
-things that we weren't testing!), or for additional information on how
-the test suite works, please see the file
-[`tests/README.md`][tests-readme].
-
-In addition, the CI machinery will run librsvg's test suite
-automatically when you push some commits.  You can tweak what happens
-during CI for your branch in the [`.gitlab-ci.yml`
-file](.gitlab-ci.yml) — for example, if you want to enable
-distro-specific tests to test things on a system that you don't have.
-
-### Testing changes
-
-The most direct way to test a change is to have an example SVG file
-that exercises the code you want to test.  Then you can rebuild
-librsvg, and run this:
-
-```
-cd /src/librsvg
-cargo build
-./target/debug/rsvg-convert -o foo.png foo.svg
-```
-
-Then you can view the resulting `foo.png` image.
-
-**Please update the test suite** with a suitable example file once you
-have things working (or before even writing code, if you like
-test-driven development), so we can avoid regressions later.  The test
-suite is documented in [`tests/README.md`][tests-readme].
-
-### Creating a merge request
-
-You may create a forked version of librsvg in [GNOME's Gitlab
-instance][gitlab], or any other publically-accessible Git hosting
-service.  You can register an account there, or log in with your
-account from other OAuth services.
-
-Note that the maintainers of librsvg only get notified about merge
-requests (or pull requests) if your fork is in
-[gitlab.gnome.org][gitlab].
-
-For technical reasons, the maintainers of librsvg do not get
-automatically notified if you submit a pull request through the GNOME
-mirror in Github.  [Please contact the maintainer][maintainer] directly if you
-have a pull request there or a branch that you would like to
-contribute.
-
-### Formatting commit messages
-
-If a commit fixes a bug, please format its commit message like this:
-
-```
-(#123): Don't crash when foo is bar
-
-Explanation for why the crash happened, or anything that is not
-obvious from looking at the diff.
-
-https://gitlab.gnome.org/GNOME/librsvg/issues/123
-```
-
-Note the `(#123)` in the first line.  This is the line that shows up
-in single-line git logs, and having the bug number there makes it
-easier to write the release notes later — one does not have to read
-all the commit messages to find the ids of fixed bugs.
-
-Also, please paste the complete URL to the bug report somewhere in the
-commit message, so that it's easier to visit when reading the commit
-logs.
-
-Generally, commit messages should summarize *what* you did, and *why*.
-Think of someone doing `git blame` in the future when trying to figure
-out how some code works:  they will want to see *why* a certain line
-of source code is there.  The commit where that line was introduced
-should explain it.
-
-### Testing performance-related changes
-
-You can use the [rsvg-bench] tool to benchmark librsvg.  It lets you
-run a benchmarking program **on an already-installed librsvg
-library**.  For example, you can ask rsvg-bench to render one or more
-SVGs hundreds of times in a row, so you can take accurate timings or
-run a sampling profiler and get enough samples.
-
-**Why is rsvg-bench not integrated in librsvg's sources?**  Because
-rsvg-bench depends on the [rsvg-rs] Rust bindings, and these are
-shipped outside of librsvg.  This requires you to first install
-librsvg, and then compile rsvg-bench.  We aim to make this easier in
-the future.  Of course all help is appreciated!
-
-### Included benchmarks
-
-The [`rsvg_internals/benches`][benches] directory has a
-couple of benchmarks for functions related to SVG filter effects.  You
-can run them with `cargo bench`.
-
-These benchmarks use the [Criterion] crate, which supports some
-interesting options to generate plots and such.  You can see the
-[Criterion command line options][criterion-options].
-
-[coc]: code-of-conduct.md
-[gitlab]: https://gitlab.gnome.org/GNOME/librsvg
-[bugs-browse]: https://gitlab.gnome.org/GNOME/librsvg/issues
-[maintainer]: README.md#maintainers
-[tests-readme]: tests/README.md
-[blog]: https://viruta.org/librsvgs-build-infrastructure-autotools-and-rust.html
-[toplevel-makefile]: Makefile.am
-[tests-readme]: tests/README.md
-[rsvg-bench]: https://gitlab.gnome.org/federico/rsvg-bench
-[rsvg-rs]: https://github.com/selaux/rsvg-rs
-[arch]: ARCHITECTURE.md
-[benches]: rsvg-internals/benches
-[Criterion]: https://crates.io/crates/criterion
-[criterion-options]: https://japaric.github.io/criterion.rs/book/user_guide/command_line_options.html
-[docker-tests-readme]: tools/docker/README.md
diff --git a/Makefile.am b/Makefile.am
index af2e6514..ac169ee9 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -243,7 +243,6 @@ CLEANFILES += rsvg-convert.1
 endif
 
 dist_doc_DATA =				\
-	CONTRIBUTING.md			\
 	README.md			\
 	code-of-conduct.md
 
diff --git a/README.md b/README.md
index c6445d58..abd9ce7b 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@ in the development guide.
 
 ***PLEASE DO NOT SEND PULL REQUESTS TO GITHUB.***  We use
 [`gitlab.gnome.org`](https://gitlab.gnome.org/GNOME/librsvg) instead.
-Please see [`CONTRIBUTING.md`][contributing] for details.
+Please see [Contributing to librsvg][contributing] for details.
 
 Table of contents:
 
@@ -58,8 +58,7 @@ need.
 
 **Bug tracking:** If you have found a bug, take a look at [our bug
 tracker][bugs].  Please see the "[reporting bugs][reporting-bugs]"
-section in the file [CONTRIBUTING.md][contributing] to see how to
-provide a good bug report.
+page in the development guide to see how to provide a good bug report.
 
 **Asking questions:** Feel free to ask questions about using librsvg
 in the [desktop-devel-list][d-d-l] mailing list.
@@ -80,14 +79,12 @@ chapter][security] in the development guide.
 # Contributing to librsvg's development
 
 There is a code of conduct for contributors to librsvg; please see the
-file [`code-of-conduct.md`][coc].
+[GNOME Code of Conduct][conduct], which is duplicated in the file
+[`code-of-conduct.md`][coc].
 
 Please see the [Development guide for librsvg][devel-guide] on how to
-contribute to librsvg, how set up your development environment, and
-for a description of librsvg's architecture.
-
-For information on how to report bugs, or how to contribute to librsvg
-in general, please see the file [`CONTRIBUTING.md`][contributing].
+contribute to librsvg, how to report bugs, how set up your development
+environment, and for a description of librsvg's architecture.
 
 # Goals of librsvg
 
@@ -195,14 +192,15 @@ ways:
 [svg]: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics
 [gnome]: https://www.gnome.org/
 [cairo]: https://www.cairographics.org/
-[coc]: code-of-conduct.md
+[coc]: https://conduct.gnome.org
+[coc-local]: code-of-conduct.md
 [autotools]: https://autotools.io/index.html
 [compiling]: https://gnome.pages.gitlab.gnome.org/librsvg/devel-docs/compiling.html
 [mail]: mailto:federico@gnome.org
 [bugs]: https://gitlab.gnome.org/GNOME/librsvg/issues
 [gi]: https://wiki.gnome.org/Projects/GObjectIntrospection
-[contributing]: CONTRIBUTING.md
-[reporting-bugs]: CONTRIBUTING.md#reporting-bugs
+[contributing]: https://gnome.pages.gitlab.gnome.org/librsvg/devel-docs/contributing.html
+[reporting-bugs]: https://gnome.pages.gitlab.gnome.org/librsvg/devel-docs/bugs.html
 [d-d-l]: https://mail.gnome.org/mailman/listinfo/desktop-devel-list
 [federico]: https://viruta.org/
 [platform]: https://developer.gnome.org/
diff --git a/code-of-conduct.md b/code-of-conduct.md
index 941574a1..a627c86f 100644
--- a/code-of-conduct.md
+++ b/code-of-conduct.md
@@ -1,74 +1,136 @@
-# Contributor Covenant Code of Conduct
+# Code of Conduct
 
-## Our Pledge
+Thank you for being a part of the GNOME project. We value your participation and want everyone to have an enjoyable and fulfilling experience. Accordingly, all participants are expected to follow this Code of Conduct, and to show respect, understanding, and consideration to one another. Thank you for helping make this a welcoming, friendly community for everyone.
 
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, gender identity and expression, level of experience,
-education, socio-economic status, nationality, personal appearance, race,
-religion, or sexual identity and orientation.
+## Scope
+
+This Code of Conduct applies to all GNOME community spaces, including, but not limited to:
+
+ * Issue tracking systems - bugzilla.gnome.org
+ * Documentation and tutorials - developer.gnome.org
+ * Code repositories - git.gnome.org and gitlab.gnome.org
+ * Mailing lists - mail.gnome.org
+ * Wikis - wiki.gnome.org
+ * Chat and forums - irc.gnome.org, discourse.gnome.org, GNOME Telegram channels, and GNOME groups and channels on Matrix.org (including bridges to GNOME IRC channels)
+ * Community spaces hosted on gnome.org infrastructure
+ * Any other channels or groups which exist in order to discuss GNOME project activities
+ * All event venues and associated spaces, including conferences, hackfests, release parties, workshops and other small events
+ * All areas related to event venues: vendor exhibit halls, staff and meal areas, connecting infrastructure like walkways, hallways, elevators, and stairs
+ * Sponsor events, either on-site or off-site
+ * Private events off-site that involve one or more attendees
+ * Social events around the main event
+ * Private conversations taking place in official conference hotels
+
+Communication channels and private conversations that are normally out of scope may be considered in scope if a GNOME participant is being stalked or harassed. Social media conversations may be considered in-scope if the incident occurred under a GNOME event hashtag, or when an official GNOME account on social media is tagged, or within any other discussion about GNOME. The GNOME Foundation reserves the right to take actions against behaviors that happen in any context, if they are deemed to be relevant to the GNOME project and its participants.
+
+All participants in GNOME community spaces are subject to the Code of Conduct. This includes GNOME Foundation board members, corporate sponsors, and paid employees. This also includes volunteers, maintainers, leaders, contributors, contribution reviewers, issue reporters, GNOME users, and anyone participating in discussion in GNOME community spaces. For in-person events, this also includes all attendees, exhibitors, vendors, speakers, panelists, organizers, staff, and volunteers.
+
+## Reporting an Incident
+
+If you believe that someone is violating the Code of Conduct, or have any other concerns, please [contact the Code of Conduct committee](gnome-code-of-conduct-reporter-guide.md).
 
 ## Our Standards
 
-Examples of behavior that contributes to creating a positive environment
-include:
+The GNOME community is dedicated to providing a positive experience for everyone, regardless of:
 
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
+ * age
+ * body size
+ * caste
+ * citizenship
+ * disability
+ * education
+ * ethnicity
+ * familial status
+ * gender expression
+ * gender identity
+ * genetic information
+ * immigration status
+ * level of experience
+ * nationality
+ * personal appearance
+ * pregnancy
+ * race
+ * religion
+ * sex characteristics
+ * sexual orientation
+ * sexual identity
+ * socio-economic status
+ * tribe
+ * veteran status
 
-Examples of unacceptable behavior by participants include:
+### Community Guidelines
 
-* The use of sexualized language or imagery and unwelcome sexual attention or
-  advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic
-  address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
+Examples of behavior that contributes to creating a positive environment include:
 
-## Our Responsibilities
+ * **Be friendly.** Use welcoming and inclusive language.
+ * **Be empathetic.** Be respectful of differing viewpoints and experiences.
+ * **Be respectful.** When we disagree, we do so in a polite and constructive manner.
+ * **Be considerate.** Remember that decisions are often a difficult choice between competing priorities. Focus on what is best for the community. Keep discussions around technology choices constructive and respectful.
+ * **Be patient and generous.** If someone asks for help it is because they need it. When documentation is available that answers the question, politely point them to it. If the question is off-topic, suggest a more appropriate online space to seek help.
+ * **Try to be concise.** Read the discussion before commenting in order to not repeat a point that has been made.
 
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
+### Inappropriate Behavior
 
-Project maintainers have the right and responsibility to remove, edit, or
-reject comments, commits, code, wiki edits, issues, and other contributions
-that are not aligned to this Code of Conduct, or to ban temporarily or
-permanently any contributor for other behaviors that they deem inappropriate,
-threatening, offensive, or harmful.
+Community members asked to stop any inappropriate behavior are expected to comply immediately.
 
-## Scope
+We want all participants in the GNOME community have the best possible experience they can. In order to be clear what that means, we've provided a list of examples of behaviors that are inappropriate for GNOME community spaces:
 
-This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community. Examples of
-representing a project or community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed
-representative at an online or offline event. Representation of a project may be
-further defined and clarified by project maintainers.
+ * **Deliberate intimidation, stalking, or following.**
+ * **Sustained disruption of online discussion, talks, or other events.** Sustained disruption of events, online discussions, or meetings, including talks and presentations, will not be tolerated. This includes 'Talking over' or 'heckling' event speakers or influencing crowd actions that cause hostility in event sessions. Sustained disruption also includes drinking alcohol to excess or using recreational drugs to excess, or pushing others to do so.
+ * **Harassment of people who don't drink alcohol or other legal substances.** We do not tolerate derogatory comments about those who abstain from alcohol or other legal substances. We do not tolerate pushing people to drink, talking about their abstinence or preferences to others, or pressuring them to drink - physically or through jeering.
+ * **Sexist, racist, homophobic, transphobic, ableist language or otherwise exclusionary language.** This includes deliberately referring to someone by a gender that they do not identify with, and/or questioning the legitimacy of an individual's gender identity. If you're unsure if a word is derogatory, don't use it. This also includes repeated subtle and/or indirect discrimination.
+ * **Unwelcome sexual attention or behavior that contributes to a sexualized environment.** This includes sexualized comments, jokes or imagery in interactions, communications or presentation materials, as well as inappropriate touching, groping, or sexual advances. Sponsors should not use sexualized images, activities, or other material. Meetup organizing staff and other volunteer organizers should not use sexualized clothing/uniforms/costumes, or otherwise create a sexualized environment.
+ * **Unwelcome physical contact.** This includes touching a person without permission, including sensitive areas such as their hair, pregnant stomach, mobility device (wheelchair, scooter, etc) or tattoos. This also includes physically blocking or intimidating another person. Physical contact or simulated physical contact (such as emojis like "kiss") without affirmative consent is not acceptable. This includes sharing or distribution of sexualized images or text.
+ * **Violence or threats of violence.** Violence and threats of violence are not acceptable - online or offline. This includes incitement of violence toward any individual, including encouraging a person to commit self-harm. This also includes posting or threatening to post other people's personally identifying information ("doxxing") online.
+ * **Influencing or encouraging inappropriate behavior.** If you influence or encourage another person to violate the Code of Conduct, you may face the same consequences as if you had violated the Code of Conduct.
+ * **Possession of an offensive weapon at a GNOME event.** This includes anything deemed to be a weapon by the event organizers.
 
-## Enforcement
+### Safety versus Comfort
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at federico@gnome.org. All
-complaints will be reviewed and investigated and will result in a response that
-is deemed necessary and appropriate to the circumstances. The project team is
-obligated to maintain confidentiality with regard to the reporter of an incident.
-Further details of specific enforcement policies may be posted separately.
+The GNOME community prioritizes marginalized people's safety over privileged people's comfort, for example in situations involving:
 
-Project maintainers who do not follow or enforce the Code of Conduct in good
-faith may face temporary or permanent repercussions as determined by other
-members of the project's leadership.
+ * "Reverse"-isms, including "reverse racism," "reverse sexism," and "cisphobia"
+ * Reasonable communication of boundaries, such as "leave me alone," "go away," or "I'm not discussing this with you."
+ * Criticizing racist, sexist, cissexist, or otherwise oppressive behavior or assumptions
+ * Communicating boundaries or criticizing oppressive behavior in a "tone" you don't find congenial
 
-## Attribution
+The examples listed above are not against the Code of Conduct. If you have questions about the above statements, please [read our document on Supporting Diversity](supporting-diversity.md).
+
+Outreach and diversity efforts directed at under-represented groups are permitted under the code of conduct. For example, a social event for women would not be classified as being outside the Code of Conduct under this provision.
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+Basic expectations for conduct are not covered by the "reverse-ism clause" and would be enforced irrespective of the demographics of those involved. For example, racial discrimination will not be tolerated, irrespective of the race of those involved. Nor would unwanted sexual attention be tolerated, whatever someone's gender or sexual orientation. Members of our community have the right to expect that participants in the project will uphold these standards.
 
-[homepage]: https://www.contributor-covenant.org
+If a participant engages in behavior that violates this code of conduct, the GNOME Code of Conduct committee may take any action they deem appropriate. Examples of consequences are outlined in the [Committee Procedures Guide](gnome-code-of-conduct-committee-procedures.md).
+
+## Procedure for Handling Incidents
+
+ * [Reporter Guide](gnome-code-of-conduct-reporter-guide.md)
+
+ * [Moderator Procedures](gnome-code-of-conduct-moderator-procedures.md)
+
+ * [Committee Procedures Guide](gnome-code-of-conduct-committee-procedures.md)
+
+## License
+
+The GNOME Code of Conduct is licensed under a [Creative Commons Attribution Share-Alike 3.0 Unported License](http://creativecommons.org/licenses/by-sa/3.0/)
+
+[![Creative Commons License](http://i.creativecommons.org/l/by-sa/3.0/88x31.png)](http://creativecommons.org/licenses/by-sa/3.0/)
+
+## Attribution
 
+The GNOME Code of Conduct was forked from the example policy from the [Geek Feminism wiki, created by the Ada Initiative and other volunteers](http://geekfeminism.wikia.com/wiki/Conference_anti-harassment/Policy), which is under a Creative Commons Zero license.
+
+Additional language was incorporated and modified from the following Codes of Conduct:
+
+ * [Citizen Code of Conduct](http://citizencodeofconduct.org/) is licensed [Creative Commons Attribution-ShareAlike 3.0 Unported License](https://creativecommons.org/licenses/by-sa/3.0/).
+ * [Code of Conduct template](https://github.com/sagesharp/code-of-conduct-template/) is licensed [Creative Commons Attribution 3.0 Unported License](http://creativecommons.org/licenses/by/3.0/) by [Otter Tech](https://otter.technology/code-of-conduct-training)
+ * [Contributor Covenant version 1.4](https://www.contributor-covenant.org/version/1/4/code-of-conduct) (licensed [CC BY 4.0](https://github.com/ContributorCovenant/contributor_covenant/blob/master/LICENSE.md))
+ * [Data Carpentry Code of Conduct](https://docs.carpentries.org/topic_folders/policies/index_coc.html) is licensed [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/)
+ * [Django Project Code of Conduct](https://www.djangoproject.com/conduct/) is licensed under a [Creative Commons Attribution 3.0 Unported License](http://creativecommons.org/licenses/by/3.0/)
+ * [Fedora Code of Conduct](http://fedoraproject.org/code-of-conduct)
+ * [Geek Feminism Anti-harassment Policy](http://geekfeminism.wikia.com/wiki/Conference_anti-harassment/Policy) which is under a [Creative Commons Zero license](https://creativecommons.org/publicdomain/zero/1.0/)
+ * [GNOME Foundation Code of Conduct](https://wiki.gnome.org/action/recall/Foundation/CodeOfConduct?action=recall&rev=48)
+ * [LGBTQ in Technology Slack Code of Conduct](https://lgbtq.technology/coc.html) licensed [Creative Commons Zero](https://creativecommons.org/publicdomain/zero/1.0/)
+ * [Mozilla Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/) is licensed [Creative Commons Attribution-ShareAlike 3.0 Unported License](https://creativecommons.org/licenses/by-sa/3.0/).
+ * [Python Mentors Code of Conduct](http://pythonmentors.com/)
+ * [Speak Up! Community Code of Conduct](http://web.archive.org/web/20141109123859/http://speakup.io/coc.html), licensed under a [Creative Commons Attribution 3.0 Unported License](http://creativecommons.org/licenses/by/3.0/)
diff --git a/devel-docs/bugs.rst b/devel-docs/bugs.rst
new file mode 100644
index 00000000..efc34c67
--- /dev/null
+++ b/devel-docs/bugs.rst
@@ -0,0 +1,50 @@
+Reporting bugs
+==============
+
+Please report bugs at https://gitlab.gnome.org/GNOME/librsvg/issues
+
+If you want to report a rendering bug, or a missing SVG feature,
+please provide an example SVG file as an attachment to your bug
+report.  It really helps if you can minimize the SVG to only the
+elements required to reproduce the bug or see the missing feature, but
+it is not absolutely required.  **Please be careful** of publishing
+SVG images that you don't want other people to see, or images whose
+copyright does not allow redistribution; the bug tracker is a public
+resource and attachments are visible to everyone.
+
+Feature requests
+----------------
+
+Librsvg aims to be a small and relatively simple SVG rendering
+library.  Currently we do not plan to support scripting, animation, or
+interactive features like mouse events on SVG elements.
+
+However, we *do* aim go provide good support for SVG's graphical
+features.  You can request new features by filing a bug report as
+noted above.
+
+It is especially helpful if you file bug for a feature request along
+with a sample SVG file that requires it, for example, a file that uses
+an SVG element or CSS property that librsvg does not yet support.
+
+
+Obtaining debug logs
+--------------------
+
+Librsvg can be asked to output debug logs.  Set the ``RSVG_LOG``
+environment variable, and then librsvg will print some 
+information to stdout:
+
+.. code-block::
+
+   $ RSVG_LOG=1 some-program-that-uses-librsvg
+   ... debug output goes here ...
+
+As of librsvg 2.43.5, there are no options you can set in the
+``RSVG_LOG`` variable; the library just checks whether that environment
+variable is present or not.
+
+Security bugs
+-------------
+
+For especially sensitive bugs, please see :doc:`security`.
diff --git a/devel-docs/contributing.rst b/devel-docs/contributing.rst
index 576f63c2..5bfbd6c4 100644
--- a/devel-docs/contributing.rst
+++ b/devel-docs/contributing.rst
@@ -1,107 +1,185 @@
-*********************************
-How you can contribute to librsvg
-*********************************
+Contributing to librsvg
+=======================
 
-Here are some projects that you can choose to contribute to librsvg.
+Thank you for looking in this document! There are different ways of
+contributing to librsvg, and we appreciate all of them.
 
-Major features
-==============
+-  `Source repository <#source-repository>`__
+-  `Feature requests <#feature-requests>`__
+-  `Hacking on librsvg <#hacking-on-librsvg>`__
 
-These are big features that may take you a few months to implement.
-Fame and glory await! :)
+All librsvg contributors are expected to follow `GNOME's Code of
+Conduct <https://conduct.gnome.org>`_.
 
-Support CSS var()
+Source repository
 -----------------
 
-This project is suitable for a few months of work, like an Outreachy
-or Summer of Code internship.  Some familiarity with CSS will be
-useful; you don't need to be an expert in it.  You need to be able to
-write Rust relatively fluently.
+Librsvg’s main source repository is at gitlab.gnome.org. You can view
+the web interface here:
 
-This is https://gitlab.gnome.org/GNOME/librsvg/-/issues/459 - In
-summary, support for var() lets CSS styles reference values defined
-elsewhere, instead of hard-coding an actual value in every place it is
-used.  For example, define a ``button-color`` variable instead of
-hard-coding ``#aabbcc`` everywhere.
+https://gitlab.gnome.org/GNOME/librsvg
 
-.. code-block:: css
+Development happens in the ``main`` branch. There are also branches for
+stable releases.
 
-   /* Define two variables */
-   :root {
-     --main-color: #06c;
-     --accent-color: #006;
-   }
+Alternatively, you can use the mirror at GitHub:
 
-   /* The rest of the CSS file */
-   #foo h1 {
-     fill: var(--main-color);
-   }
+https://github.com/GNOME/librsvg
 
-In the context of librsvg, this would be useful in several situations:
+Note that we don’t do bug tracking in the GitHub mirror; see the next
+section.
 
-- Allow toolkits to specify a user stylesheet while rendering a
-  document, to recolor items in SVGs for icons.  They can already do
-  this by using CSS selectors (e.g. change the fill color in elements
-  that have the ``button`` class), but CSS ``var()`` would be nice for
-  flexibility.
+If you need to publish a branch, feel free to do it at any
+publically-accessible Git hosting service, although gitlab.gnome.org
+makes things easier for the maintainers of librsvg.
 
-- Part of supporting `SVG Native`_ involves adding support for
-  ``var()``.  This is useful for emoji fonts which include glyphs in
-  SVG format.
+Hacking on librsvg
+------------------
 
-There is a pretty complete in `implementation in Servo`_.  You can use
-it for inspiration, or cut&paste it into librsvg; it will need some
-changes, and probably also some additions to librsvg's existing
-machinery for CSS.
+See the rest of this development guide, especially the chapter on
+:doc:`architecture`, and the tutorial on :doc:`adding_a_property`.
 
-One particularly interesting bit in Servo's implementation is that it guards against exponential expansion of malicious variables.
+The library’s internals are being documented at
+https://gnome.pages.gitlab.gnome.org/librsvg/internals/librsvg/index.html
 
-.. code-block:: css
+What can you hack on?
 
-   :root {
-     --prop1: lol;
-     --prop2: var(--prop1) var(--prop1);
-     --prop3: var(--prop2) var(--prop2);
-     --prop4: var(--prop3) var(--prop3);
-     /* expand to --prop30 */
-   }
+- `Bugs for
+  newcomers <https://gitlab.gnome.org/GNOME/librsvg/-/issues?label_name%5B%5D=4.+Newcomers>`__
+- Pick something from the `development
+  roadmap <https://gnome.pages.gitlab.gnome.org/librsvg/devel-docs/roadmap.html>`__.
+- Tackle one of the `bigger projects
+  <https://gitlab.gnome.org/GNOME/librsvg/-/issues/?label_name%5B%5D=project>`_.
 
-A naive implementation would make the consume a few gigabytes of
-memory; grep for "exponentially" in Servo's code to see how it guards
-against that.
+Working on the source
+~~~~~~~~~~~~~~~~~~~~~
 
-.. _SVG Native: https://gitlab.gnome.org/GNOME/librsvg/-/issues/689
+Librsvg uses an autotools setup, which is described in detail `in this
+blog
+post <https://viruta.org/librsvgs-build-infrastructure-autotools-and-rust.html>`__.
 
-.. _implementation in Servo: https://github.com/servo/servo/blob/master/components/style/custom_properties.rs
+If you need to **add a new source file**, you need to do it in the
+toplevel ``Makefile.am``. *Note that this is for both
+C and Rust sources*, since ``make(1)`` needs to know when a Rust file
+changed so it can call ``cargo`` as appropriate.
 
-Support CSS calc()
-------------------
+It is perfectly fine to ask the maintainer if you have questions about
+the Autotools setup; it’s a tricky bit of machinery, and we are glad
+to help.
+
+Continuous Integration
+~~~~~~~~~~~~~~~~~~~~~~
+
+If you fork librsvg in ``gitlab.gnome.org`` and push commits to your
+forked version, the Continuous Integration machinery (CI) will run
+automatically.
+
+The CI infrastructure is documented in the :doc:`ci` chapter.
+
+When you create a merge request, or push to a branch in a fork of
+librsvg, GitLab's CI will run a *pipeline* on the contents of your
+push: it will run the test suite, linters, try to build the
+documentation, and generally see if everything that makes
+:doc:`product` is working as intended.  If any tests fail, the
+pipeline will fail and you can then examine the build artifacts of
+failed jobs to fix things.
+
+**Automating the code formatting:** You may want to enable a
+`client-side git
+hook <https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks>`__ to
+run ``rustfmt`` before you can commit something; otherwise the ``lint``
+stage of CI pipelines will fail:
+
+1. ``cd librsvg``
+
+2. ``mv .git/hooks/pre-commit.sample .git/hooks/pre-commit``
+
+3. Edit ``.git/hooks/pre-commit`` and put in one of the following
+   commands:
+
+-  If you want code reformatted automatically, no questions asked:
+   ``cargo fmt`` **Note:** if this actually reformats your code while
+   committing, you’ll have to re-stage the new changes and
+   ``git commit --amend``. Be careful if you had unstaged changes that
+   got reformatted!
+
+-  If you want to examine errors if rustfmt doesn’t like your
+   indentation, but don’t want it to make changes on its own:
+   ``cargo fmt --all -- --check``
+
+Test suite
+~~~~~~~~~~
+
+All new features need to have corresponding tests.  Please see the
+file ``tests/README.md`` to see how to add new tests to the test suite.  In short:
+
+- Add unit tests in the ``src/*.rs`` files for internal things like
+  parsers or algorithms.
+
+- Add rendering tests in ``tests/src/*.rs`` for SVG or CSS features.
+  See ``tests/README.md`` for details on how to do this.
+
+In either case, you can run ``cargo test`` if you set up your
+development environment as instructed in the :doc:`devel_environment`
+chapter.  Alternatively, push your changes to a branch, and watch the
+results of its CI pipeline.
+
+Creating a merge request
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may create a forked version of librsvg in `GNOME’s Gitlab instance
+<https://gitlab.gnome.org/GNOME/librsvg>`__,. You can register an
+account there, or log in with your account from other OAuth services.
+
+For technical reasons, the maintainers of librsvg do not get
+automatically notified if you submit a pull request through the GNOME
+mirror in GitHub.  In that case, please create a merge request at
+``gitlab.gnome.org`` instead; you can ask the maintainer for assistance.
+
+Formatting commit messages
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If a commit fixes a bug, please format its commit message like this:
+
+::
+
+   (#123): Don't crash when foo is bar
+
+   Explanation for why the crash happened, or anything that is not
+   obvious from looking at the diff.
+
+   Fixes https://gitlab.gnome.org/GNOME/librsvg/issues/123
+
+Note the ``(#123)`` in the first line. This is the line that shows up in
+single-line git logs, and having the bug number there makes it easier to
+write the release notes later — one does not have to read all the commit
+messages to find the ids of fixed bugs.
+
+Also, please paste the complete URL to the bug report somewhere in the
+commit message, so that it’s easier to visit when reading the commit
+logs.
+
+Generally, commit messages should summarize *what* you did, and *why*.
+Think of someone doing ``git blame`` in the future when trying to figure
+out how some code works: they will want to see *why* a certain line of
+source code is there. The commit where that line was introduced should
+explain it.
+
+Testing performance-related changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use the
+`rsvg-bench <https://gitlab.gnome.org/federico/rsvg-bench>`__ tool to
+benchmark librsvg.  For example, you can ask rsvg-bench
+to render one or more SVGs hundreds of times in a row, so you can take
+accurate timings or run a sampling profiler and get enough samples.
+
+Included benchmarks
+~~~~~~~~~~~~~~~~~~~
+
+The ``benches/`` directory has a couple of benchmarks for functions
+related to SVG filter effects.  You can run them with ``cargo bench``.
 
-This project is suitable for a few months of work, like an Outreachy
-or Summer of Code internship.
-
-Some familiarity with CSS will be useful; you don't need to be an
-expert in it.  You need to be able to write Rust relatively fluently.
-It will be very useful to have some familiarity with implementing
-simple interpreters or evaluators - for example, parsing and computing
-an expression like ``5 + 3 * (2 - 4)``; if you have already written a
-parser and Abstract Syntax Tree for that kind of thing, this project
-will be a lot easier.
-
-This is https://gitlab.gnome.org/GNOME/librsvg/-/issues/843 - support
-calc() expressions in CSS.  For example, parameterize an element's
-width by using ``width="calc(100% - 40px)"`` (this would use the
-viewport's width of 100%, and subtract 40 pixels).
-
-The issue linked in the previous paragraph has plenty of
-implementation advice.  It requires some substantial preliminary work,
-like completing the separation between specified values and computed
-values in librsvg's CSS implementation.  Please ask the maintainer to
-prioritize this work if you intend to implement CSS calc().
-
-Performance tracking
---------------------
-
-See the - :doc:`performance_tracking` document.  This does not involve
-hacking on librsvg itself, but rather creating an infrastructure to
-track performance metrics.
+These benchmarks use the
+`Criterion <https://crates.io/crates/criterion>`__ crate, which supports
+some interesting options to generate plots and such.
diff --git a/devel-docs/index.rst b/devel-docs/index.rst
index 856a3920..097fb514 100644
--- a/devel-docs/index.rst
+++ b/devel-docs/index.rst
@@ -10,6 +10,7 @@ Development guide for librsvg
    roadmap
    compiling
    security
+   bugs
 
 .. toctree::
    :caption: Getting Started as a Contributor
@@ -64,6 +65,7 @@ evolved into a few different tools.
 - :doc:`compiling` - Cross compilation, debug/release builds, special options.
 - :doc:`security` - Reporting security bugs, releases with security
   fixes, security of dependencies.
+- :doc:`bugs`
 
 Getting started
 ---------------
diff --git a/devel-docs/security.rst b/devel-docs/security.rst
index 95b2f749..66862be0 100644
--- a/devel-docs/security.rst
+++ b/devel-docs/security.rst
@@ -177,7 +177,7 @@ Gdk-pixbuf depends on **libpng**, **libjpeg**, and other libraries for
 different image formats.
 
 Security considerations for librsvg
-===================================
+-----------------------------------
 
 **Built-in limits:** Librsvg has built-in limits for the following: