Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update CONTRIBUTING.md #2159

Merged
merged 2 commits into from
Sep 2, 2022
Merged

Update CONTRIBUTING.md #2159

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b2db818
Update CONTRIBUTING.md
inikolaidis Aug 30, 2022
0c001d0
Update CONTRIBUTING.md
inikolaidis Aug 31, 2022
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
87 changes: 26 additions & 61 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,80 +1,45 @@
# Welcome!

If you are reading this document then you are interested in contributing to Islandora. All contributions are welcome: use-cases, documentation, code, patches, bug reports, feature requests, etc. You do not need to be a programmer to speak up!
If you are reading this document then you are interested in contributing to Islandora. You do not need to be a programmer to speak up! By joining the Islandora community, you agree to abide by the Islandora [Code of Conduct](https://www.islandora.ca/code-of-conduct).

## Weekly Open Tech Call

The Islandora Tech Call meets each Wednesday at 1:00 PM Eastern. You can view meeting agendas, notes, and call-in information [here](https://github.com/Islandora/islandora-community/wiki/Weekly-Open-Tech-Call). Anybody is welcome to join the call, and add items to the agenda.

## Github

You can use Github to:

- report bugs
- request documentation or report unclear documentation
- request features
- submit use cases

See more about onboarding to the Islandora community, including Islandora on Github, on the islandora-community Onboarding page [here](https://github.com/Islandora/islandora-community/wiki/Onboarding-Checklist#general-onboarding).

### Report a bug
To report a bug you should [open an issue in the Islandora repository](https://github.com/Islandora/documentation/issues/new/choose), selecting the **Bug report** template.

Please summarize the bug along best practice guidelines outlined in the template. In order to help us understand and fix the bug it would be great if you could provide us with:

1. The steps to reproduce the bug. This includes information about e.g. the Islandora version you were using along with the versions of stack components.
2. The expected behavior.
3. The actual, incorrect behavior.
## Join the community!
**Onboarding Form: Submit your information through the [Onboarding Form](https://forms.gle/V9vHdbFxj4wydJCs6), and we can invite you to all the listed channels below.**

Feel free to search the issue queue for existing issues (aka tickets) that already describe the problem; if there is such a ticket please add your information as a comment.
* **Slack:** Use [this invite link](https://join.slack.com/t/islandora/shared_invite/zt-1ac9k1xs5-Hbeit2twqexyJCxZQg9ZBQ) to join our Slack workspace. If you're not sure what channels you're looking for, get started by asking your questions in the #general channel!

**If you want to provide a pull along with your bug report:**
* **Google Group:** Subscribe to the mailing list by joining the [Google Group](https://groups.google.com/g/islandora).

That is great! In this case please send us a pull request as described in the section _Create a pull request_ below.
* **Github:** Although you can participate without a Github account, having one ensures you can be made a member of the Islandora General Members team to better enable your access to the Islandora project. Additionally, it will allow you to be tagged on relevant issues or pull requests that are of interest to you! To become a part of the Islandora General Members Github team, email [email protected] or [use the Onboarding form](https://forms.gle/V9vHdbFxj4wydJCs6).

### Documentation

You can contribute documentation in two different ways. One way is to open an issue [here](https://github.com/Islandora/documentation/issues/new/choose), using the **Documentation** template. This template will ask for further information about where your documentation request belongs and what it should contain.
Another way is by pull request, which is the same process as [Contribute Code](https://github.com/Islandora/documentation/blob/main/CONTRIBUTING.md#contribute-code) and requires the same Contributor License Agreements. All documentation resides in [`docs`](https://github.com/Islandora/documentation/tree/main/docs).

### Request a new feature

To request a new feature, [open an issue in the Islandora repository](https://github.com/Islandora/documentation/issues/new/choose) using the **Feature request** template. Summarize the desired functionality, making sure to note whether the feature request is a change to existing behaviour of islandora or if it is introducing a new addition or behaviour. Feature requests may be supported by specific use cases. To create supporting Use case issues and link them to your feature request, see the _Use cases_ section below.


### Use cases
If you would like to submit a use case to the Islandora project, please submit an issue [here](https://github.com/Islandora/documentation/issues/new/choose) using the **Use Case template**. You may want to create a user story to support your use case. Read more about user stories [here](https://en.wikipedia.org/wiki/User_story#Principle).

### Contribute code

Before you set out to contribute code or documentation you will need to have completed a [Contributor License Agreement](https://github.com/Islandora/islandora-community/wiki/Onboarding-Checklist#contributor-license-agreements) or be covered by a [Corporate Contributor License Agreement](https://github.com/Islandora/islandora-community/wiki/Onboarding-Checklist#contributor-license-agreements).
## Weekly Open Tech Call

_If you are interested in contributing code to Islandora but do not know where to begin:_
Attend our weekly Zoom meetings on Wednesdays at 1:00 PM EST! You can access these meetings through our [Agendas](https://github.com/Islandora/islandora-community/wiki/Tech-Call-Meetings-2022) or our [Community Calendar](https://calendar.google.com/calendar/embed?src=96s6v709n719hapqtt9m8vj588%40group.calendar.google.com&ctz=America%2FToronto). We discuss the past week's Github activity in Issues and Pull Requests, and any other topics that are raised. Anybody is welcome to join the call, and add items to the agenda.

In this case you should [browse open issues](https://github.com/Islandora/documentation/issues) and check out [use cases](https://github.com/Islandora/documentation/labels/Type%3A%20use%20case).
## Github Issues

If you are contributing Drupal code, it must adhere to [Drupal Coding Standards](https://www.drupal.org/coding-standards); Travis CI will check for this on pull requests.
Anyone with a [Github account](https://github.com/signup?source=login) can make issues. Please check the applicable places first to see if there's already a ticket.

Contributions to the Islandora codebase should be sent as GitHub pull requests. See section _Create a pull request_ below for details. If there is any problem with the pull request we can work through it using the commenting features of GitHub.
Issues should be added in the individual module or component's repository where applicable. For issues that are broader in scope than one module, or about the official [Islandora documentation](https://islandora.github.io/documentation/), open an issue in the [Documentation repository](https://github.com/Islandora/documentation/issues). This is also the repository for hundreds of "legacy" (but still valid) tickets from before we opened issue queues on individual repositories.

* For _small patches_, feel free to submit pull requests directly for those patches.
* For _larger code contributions_, please use the following process. The idea behind this process is to prevent any wasted work and catch design issues early on.
Issue templates are provided for the following:

1. [Open an issue](https://github.com/Islandora/documentation/issues/new), prepending "Enhancement:" in the title if a similar issue does not exist already. If a similar issue does exist, then you may consider participating in the work on the existing issue.
2. Comment on the issue with your plan for implementing the issue. Explain what pieces of the codebase you are going to touch and how everything is going to fit together.
3. Islandora committers will work with you on the design to make sure you are on the right track.
4. Implement your issue, create a pull request (see below), and iterate from there.
* **Bug Report:** Report something not working in Islandora software.
* **Documentation:** Let us know if documentation is unclear, or missing.
* **Feature Request:** Start here if you would like to request a specific feature. Note that these should usually be supported by Use Cases.
* **Use Case:** Start here if you would like to outline a need with a defined scope to be addressed by Islandora software.

### Create a pull request
Issues are reviewed during the [Weekly Open Tech Call](https://github.com/Islandora/islandora-community/wiki/Tech-Call-Meetings-2022) every Wednesday at 1:00 p.m. Eastern.

Take a look at [Creating a pull request](https://help.github.com/articles/creating-a-pull-request). In a nutshell you need to:
## Github Pull Requests

1. [Fork](https://help.github.com/articles/fork-a-repo) this repository to your personal or institutional GitHub account (depending on the CLA you are working under). Be cautious of which branches you work from though (you'll want to base your work off main, or for Drupal modules use the most recent version branch). See [Fork a repo](https://help.github.com/articles/fork-a-repo) for detailed instructions.
2. Commit any changes to your fork.
3. Send a [pull request](https://help.github.com/articles/creating-a-pull-request) using the [pull request template](https://github.com/Islandora/documentation/blob/main/.github/PULL_REQUEST_TEMPLATE.md) to the Islandora GitHub repository that you forked in step 1. If your pull request is related to an existing issue -- for instance, because you reported a [bug/issue](https://github.com/Islandora/documentation/issues) earlier -- prefix the title of your pull request with the corresponding issue number (e.g. `issue-123: ...`). Please also include a reference to the issue in the description of the pull. This can be done by using '#' plus the issue number like so '#123', also try to pick an appropriate name for the branch in which you're issuing the pull request from.
If you have code to address an issue, or can offer documentation, [please create a pull request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) in the appropriate repository.
Before we can merge your pull request, you must have a signed CLA or CCLA (see [below](https://islandora.github.io/documentation/contributing/CONTRIBUTING/#contributor-license-agreements)).
Code PRs must conform to [Drupal Coding Standards](https://islandora.github.io/documentation/technical-documentation/checking-coding-standards/), and [Documentation](https://islandora.github.io/documentation/) PRs must conform to our [Documentation Style Guide](https://islandora.github.io/documentation/contributing/docs_style_guide/). There are no guides specific to READMEs or other documentation (help text, etc) that lives in Drupal, but please try to write clearly and follow existing practices.
See more in our [Contributing Workflow](https://islandora.github.io/documentation/contributing/contributing-workflow/).

You may want to read [Syncing a fork](https://help.github.com/articles/syncing-a-fork) for instructions on how to keep your fork up to date with the latest changes of the upstream (official) repository.
## New Modules
If you have code that doesn't fit within the scope of Islandora's existing repositories, but that the Islandora community is in a better position to maintain than you are, please consider using the [LSAP Process](https://docs.google.com/document/d/16_-Yk3O-gmo93ppiRmoLltkkr4fSUp1IC72hzJz6lm8/edit?usp=sharing) to contribute your code to the ownership of the Islandora Foundation.

## License Agreements
## Contributor License Agreements

The Islandora Foundation requires that contributors complete a [Contributor License Agreement](https://github.com/Islandora/islandora-community/wiki/Onboarding-Checklist#contributor-license-agreements) or be covered by a [Corporate Contributor License Agreement](https://github.com/Islandora/islandora-community/wiki/Onboarding-Checklist#contributor-license-agreements). The signed copy of the license agreement should be sent to <a href="mailto:[email protected]?Subject=Contributor%20License%20Agreement" target="_top">[email protected]</a>. This license is for your protection as a contributor as well as the protection of the Foundation and its users; it does not change your rights to use your own contributions for any other purpose.
Before you set out to contribute code you will need to have completed a [Contributor License Agreement](https://github.com/Islandora/islandora-community/wiki/Onboarding-Checklist#contributor-license-agreements) or be covered by a [Corporate Contributor License Agreement](https://github.com/Islandora/islandora-community/wiki/Onboarding-Checklist#contributor-license-agreements). This license is for your protection as a contributor as well as the protection of the Foundation and its users; it does not change your rights to use your own contributions for any other purpose.