babelfishpg.org Website

Babelfishpg.org website

This repo contains the source for the babelfishpg.org website. The Babelfish project welcomes contributions to the site - review CONTRIBUTING to learn more. We also welcome your feedback:

about new content,
to remove or report inaccuracies,
to fill information gaps,
to fix typos or grammatical errors, and
to improve clarity.

Building the website on your local system

You can build the Babelfish website on your local system with either Docker or Jekyll:

After installing Docker, you can build the site in a container with the command, docker-compose up -d.
After installing Bundler and Jekyll, invoke the following command to prepare the project files for the build:

bundle install

Then, you can build the HTML files with the following command:

bundle exec jekyll build

The HTML output is generated in the /_site folder; please note that while you can review individual pages or updates, the output may contain broken links. To build the Babelfish website, and deploy the build on your desktop in a browser, use the commands:

bundle exec jekyll serve -w

Visit the Jekyll web site for a full list of build configuration options.

Link checker

The Babelfish project uses a link checker to ensure that we don't have any broken links on the website. The link checker doesn't run by default since it can significantly slow down the build. To run the link checker during a build, include the option=value pair that best describes the behavior of the build, and the range you'd like to check. Include:

JEKYLL_LINK_CHECKER to validate links, without stopping the build for a broken link.

JEKYLL_FATAL_LINK_CHECKER to validate links, stopping the build for a broken link.

Pair the link checker behavior with a range option; each option tests a larger range of links:

internal: validates only the internal links.
forced: validates internal links and links that are technically internal but that link to an external page. For example, /docs.
all: validates all links. This option does not retry links or follow redirection links such as HTTP:429 (too many attempts, retry after), or HTTP:301 (Permanent redirect).
retry: validates all the links but also retries links with a retry-able HTTP header.

For example:

JEKYLL_FATAL_LINK_CHECKER=all bundle exec jekyll build

Writing style guidelines

When submitting content for addition to the Babelfish guide, please consider the following guidelines.

You should:

Keep the content informal and to the point.
Use short but complete sentences.
Be consistent and correct with punctuation and capitalization.
Use bulleted lists and tables where appropriate.
Focus on the user’s task, and the steps required to accomplish it. If all of the steps or information is not included on one page, provide supporting links.
Share concise, technically accurate content that helps the user understand the product and accomplish a task.
Write in active voice, with the assumption that the reader is the person that will perform actions: “You should specify the password associated with...” or instructional: “Specify the password associated with...”.
Use contractions where appropriate: we’re, isn’t, can’t, and so on.

When referring to proprietary products, use the complete company name and the product name once at the start of the page; thereafter, use only the product name.

The term Microsoft SQL Server is the complete company name and product name. For example: Babelfish extends your PostgreSQL database with the ability to accept database connections from Microsoft SQL Server clients.
The term SQL Server refers to the database, the database content, and transactions/procedures/functions that involve more than SQL syntax. For example: The TDS port accepts SQL Server commands, with the limitations discussed later in this guide.
Use T-SQL when referring to syntax or language. For example: You should use correct T-SQL syntax when forming commands.
Use TDS when referring to the protocol used by SQL Server. For example: The server listens for client connections in TDS protocol.

Don't:

Assume that the user has experience using PostgreSQL; many Babelfish users have SQL Server experience, but haven't used PostgreSQL.
Use jargon or slang - whether marketing, developer, or internal terms
Use colloquialisms or regionally understood expressions (that may or may not be known to other Babelfish users)
Documentation shouldn't include future plans; that information belongs in a product roadmap.

The Babelfish project supports an environment of diversity and equity. In the interest of promoting inclusivity, the following words (unless used in a literal/strictly technical manner such as an object name or command) should be avoided. Alternatives are recommended below. Instead of:

execute → use start or run
abort → use stop
enable → use turn on, activate, start
disable → use turn off, deactivate, stop
kill → use end or stop
blacklist → use deny list
master → use primary, main, or leader
hang → use stop responding
slave → use secondary, replica, or standby
invalid → use not valid
segregate → use isolate or separate
it is recommended --> use we recommend

If you are sharing documentation about a new feature, it should describe the feature and include usage instructions and examples where practical. This is especially true for user interfaces and new SQL functions.

Submitting a pull request

The Babelfish project welcomes contributions of features and documentation. You can submit a pull request through Github to contribute to the Babelfish project. Note that commits to the Github repo must be signed off with your name and email; include the -s and -m options when submitting your patch.

When submitting code or documentation, ensure that your code adheres to community standards and documentation and comments conform to the Writing style guidelines. This project has adopted the Open Source Code of Conduct; for more information see the Code of Conduct.

Before submitting a pull request, make sure that your change is properly tested; changes shouldn't compromise existing features. We strongly recommend you test your patch before you send a pull request to development. When you submit a new feature, include test cases and documentation for the feature. Patches that don't include tests and documentation won't be accepted.

If you contribute code, make sure that your code does not violate 3rd party rights; check for intellectual property conflicts before you submit a pull request that includes content from other projects.

Credits

Babelfish would not be possible without the hard work and dedication of the people who have contributed to PostgreSQL. Everyone involved in the development of PostgreSQL has our gratitude.

This website was forked from the BSD-licensed djangoproject.com and merged with the just-the-docs theme.

This project is licensed under the BSD-3-Clause License.