Skip to content

Latest commit

 

History

History
219 lines (159 loc) · 7.68 KB

CONTRIBUTING.md

File metadata and controls

219 lines (159 loc) · 7.68 KB
Raw

Contributing to Gollum

Thanks for your interest in the gollum project!

Submitting an Issue

Please note that the issue tracker is meant for:

  1. Bug reports.
  2. Feature requests.

If your have problems using or installing the software which stem from bugs in the software or a lack of documentation, we are always happy to help out! However, for ordinary usage questions, please consider asking elsewhere, for instance on StackOverflow.

Gollum supports custom macros for the creation of additional wiki markup tags. Please do not use this tracker to request macros specific to your situation. However, if you have or are working on a macro that you think may be useful to more users, you can share it as a GitHub gist and link to it in the wiki.

Before submitting an issue, please carefully look through the following places to make sure your problem is not already addressed:

  1. The issue tracker.
  2. The README.
  3. The project's wiki.

Security vulnerabilities can be reported directly to the maintainers using these GPG keys:

Lastly, please consider helping out by opening a Pull Request!

Triaging Issues Open Source Helpers

You can triage issues which may include reproducing bug reports or asking for vital information, such as version numbers or reproduction instructions. If you would like to start triaging issues, one easy way to get started is to subscribe to gollum on CodeTriage.

Set up your development environment

If you want to hack on Gollum, you'll need to set up a development environment.

To get started, you'll need:

  • A recent version of Git
  • A recent version of Ruby.
  • A recent version of Node JS.

Refer to their installation instructions. Installation methods differ depending on your operating system.

Once you have those:

  • Install Bundler, the Ruby package manager. In a terminal: 
    gem install bundler
  • Install Yarn, a JavaScript package manager. See Yarn's install guide.

Now, you can start setting up Gollum to run locally:

  1. Clone the git repository. In a terminal:

    git clone https://github.com/gollum/gollum.git

  2. Change directory into the cloned project:

    cd gollum

  3. Bundle the project's Ruby dependencies using Bundler:

    [sudo] bundle install

  4. Install the project's JavaScript dependencies using Yarn:

    yarn install

  5. Configure the local git repository to use master as the default branch when initializing new git repositories:

    git config --local init.defaultbranch=master

    This is currently required make the test suite pass when running it locally.1

If all went well, you should now be able to run the test suite using the following command:

bundle exec rake

If you already have a Gollum wiki, you can also browse it via your local version of Gollum:

bundle exec gollum <path/to/my/wiki/root>

Or you can clone an example wiki and browse that:

git clone test/examples/lotr.git ~/lotr-wiki
bundle exec gollum ~/lotr-wiki

With this, you're ready to start contributing and open your first pull request.

Opening a Pull Request

Pull Requests fixing bugs, implementing new features, or updating documentation and dependencies are all very welcome! If you would like to help out with the project, you can pick an open issue from the issue tracker. We're more than happy to help you get started! Here's how you can proceed:

  1. Fork and clone Gollum. See Set up your development environment.
  2. Create a thoughtfully named topic branch to contain your changes.
  3. If you haven't installed dependencies yet, navigate to your clone and execute: 
    [sudo] bundle install
  4. Hack away.
  5. Add your own tests and make sure they're all still passing.
  6. If some of your changes deserve a mention on Gollum's home page, edit the README accordingly.
  7. If necessary, rebase your commits into logical chunks, without errors.
  8. Push the branch to your fork on GitHub.
  9. Create a pull request for Gollum.

Do not change Gollum's version number, we will do that on our own.

Running tests

  1. Install Bundler.
  2. Navigate to the cloned source of Gollum.
  3. Install dependencies: 
    [sudo] bundle install
  4. Run the tests: 
    bundle exec rake test

To profile slow tests, you can use the --verbose flag:

bundle exec rake test TESTOPTS="--verbose"

You can also run a single test file with the following command:

bundle exec ruby <test/test_the_file_i_want_to_run.rb>

Working with test repositories

An example of how to add a test file to the bare repository lotr.git.

mkdir tmp
cd tmp
git clone ../test/examples/lotr.git/
git log
echo "test" > test.md
git add .
git commit -am "Add test"
git push ../lotr.git/ master

Assets

Gollum uses yarn and sprockets to manage assets. By default, Gollum uses the precompiled static assets that are packaged with the gem (under lib/gollum/public/assets). If you're making changes to Gollum's JavaScript or (S)CSS assets, you might want to develop by calling gollum with the --development-assets flag. This will cause the application to use the unpackaged assets that you are editing (under lib/gollum/public/gollum/ and in your local node_modules directory), so you can test and tweak. Once you are satisfied with your changes, it's time to update the static assets!

For convenience, Gollum also allows developers to set a custom location for node_modules (by default expected to be in the root of the project) when using --development-assets. Set the GOLLUM_DEV_ASSETS environment variable to do this, e.g.: GOLLUM_DEV_ASSETS=/path/to/my/node_modules gollum --development-assets

Updating static assets

This is necessary whenever changes have been made to the assets in lib/gollum/public/gollum/javascript (mostly SASS, CSS, and JS files), to ensure the changes are also present in the released version of the gem.

Steps:

  1. git rm -r lib/gollum/public/assets
  2. bundle exec rake precompile
  3. git add lib/gollum/public/assets
  4. git commit

Releasing the gem

Gollum uses Semantic Versioning.

x.y.z

For z releases:

rake bump
rake release

For x.y releases:

# First update VERSION in lib/gollum.rb and then:
rake gemspec
rake release

Footnotes

  1. Gollum's test suite will clone and initialize test git repositories using your system's git executable. These test git repositories are committed to the codebase, and all of them use master as the HEAD. If init.defaultbranch is set to main or something else in your global git configuration file, this will cause many tests to erroneously fail. It's on our to-do list to move these committed git repos to using a main branch. ↩