diff --git a/README.md b/README.md index 54bb312..2f1a7dc 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,87 @@ The following scripts are made available via [package.json](./package.json): ## Contributing -Contributions are welcome! Please feel free to submit a Pull Request. +### Reporting an Issue + +Issues for ArchivesSpace's technical documentation are [tracked in Jira.](https://archivesspace.atlassian.net/jira/software/projects/TD/boards/57) If there isn't a ticket in this system, go ahead and make one. Be +sure to include a **title and clear description** with as much relevant +information as possible. + +### Creating a Pull Request + +#### Fork & create a branch + +When you are ready to start working on an issue, please assign it to yourself +as an indication that you are working on it. Then [fork TechDocs][https://github.com/archivesspace/tech-docs/fork] and +create a branch with a descriptive name. + +A good branch name would include the ticket number in it. For example, if you +are working on JIRA ticket TD-123: + +```sh +git checkout -b TD-123-descriptive-short-title +``` + +#### Get the test suite running + +Before running any tests, you will need to set up your environment. See [Running TechDocs locally](#running-techdocs-locally). + +#### Implement your fix, enhancement or new feature + +At this point, you're ready to make your changes! Feel free to ask for help; +remember everyone is a beginner at first + +- ArchivesSpace Program Team - ArchivesSpaceHome@lyrasis.org + +#### Run tests and style code + +Before making a pull request, make sure tests run successfully and code adheres to style rules. See [Testing](#testing) for running tests. To apply style rules automatically: + +```console +npm run prettier:fix +npm run stylelint:fix +``` + +#### Make a Pull Request + +At this point, you should switch back to your main branch and make sure it's +up to date with ArchivesSpace's main branch: + +```sh +git remote add upstream git@github.com:archivesspace/tech-docs.git +git checkout main +git pull upstream main +``` + +Then update your feature branch from your local copy of main, and push it! + +```sh +git checkout TD-123-descriptive-short-title +git rebase main +git push --set-upstream origin TD-123-descriptive-short-title +``` + +Finally, go to GitHub and [make a Pull Request][https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request] :D + +Our CI process will run all test suites against the pushed branch. We care about +quality, so your Pull Request won't be merged until all test suites pass. If any linting checks fail, the PR reviewer can fix those issues. + +##### What happens after you submit a Pull Request? + +All Pull Requests are reviewed by at least one member of the ArchivesSpace [Core Committer's Group](https://archivesspace.atlassian.net/wiki/spaces/ADC/pages/102893918/Core+Committers+Group). + +A core committer reviews the issue/ticket associated with the Pull Request to make +sure they understand what the code changes are supposed to do. Next, they review +the code changes to see the proposed solution. Then they checkout the branch to +test the solution in a running instance of ArchivesSpace. + +During the review, the core committer may have comments or ask questions in the +Pull Request. Once the comment/questions have been answered/resolved, a Pull +Request can only be accepted and merged into the core code base by a core +committer if: + +- All test suites are passing. +- It is up-to-date with current main. ## 📖 Additional Resources