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

Jump to bottom

Update contributing guide #1876

Closed
wants to merge 7 commits into from
Closed

Update contributing guide #1876

Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
549ad02
Update contributing guide
replaceafill Nov 29, 2023
c14ed7b
Use https links
replaceafill Nov 29, 2023
5667c44
Update table of contents
replaceafill Nov 30, 2023
4dcf6e9
Remove trailing spaces
replaceafill Nov 30, 2023
bcc7d90
Use mailto addresses and backticks
replaceafill Nov 30, 2023
f14ddfc
Add link to security policy
replaceafill Nov 30, 2023
bfafcb3
Update code review document
replaceafill Nov 30, 2023
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
70 changes: 28 additions & 42 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ It is recommended to file issues there rather than in any of the
Archivematica-related code repositories. Artefactual staff also use GitHub
issues for any work they do on the Archivematica project.

You can also post in our [user] mailing list. A post to the mailing list is
You can also post in our user [mailing list]. A post to the mailing list is
always welcome, especially if you're unsure if it's a bug or a local problem!

Useful questions to answer if you're having problems include:
Expand Down Expand Up @@ -87,16 +87,15 @@ outside contributors.

Here's an outline of the contribution process:

1. File an issue in the
[Archivematica Issues repo].
1. File an issue in the [Archivematica Issues repo].
2. Fork the Artefactual project on GitHub, and commit your changes to a branch
in your fork.
3. Open a pull request.
4. Back and forth discussion with developers on the branch.
5. Make any changes suggested by reviewers.
6. Repeat 3 and 4 as necessary.
7. Clean up commit history, if necessary.
8. Sign a Contributor's Agreement, if you haven't already.
3. Open a pull request using `qa/1.x` as the base branch.
4. Sign a [Contributor's Agreement], if you haven't already.
5. Back and forth discussion with developers on the branch.
6. Make any changes suggested by reviewers.
7. Repeat 5 and 6 as necessary.
8. Clean up commit history, if necessary.
9. Your branch will be merged!

### Permalinks
Expand Down Expand Up @@ -213,8 +212,8 @@ [email protected].
Alternatively, you may send a printed, signed agreement to:

Artefactual Systems Inc.
201 - 301 Sixth Street
New Westminster BC V3L 3A7
#1 -10318 Whalley Blvd.
Surrey, BC V3T 4H4
Canada

## Contribution standards
Expand All @@ -236,18 +235,16 @@ very good linters available that you can run to check style in your code.
We have integrated these tools with our CI, i.e. pull requests will fail to
build when the tools above report errors.

Additionally [Pylint] is used by developers internally at Artefactual to
Additionally [pre-commit] is used by developers internally at Artefactual to
highlight other potential areas of improvement during code-review.

#### Some extra notes

A few additional stylistic preferences might not get flagged by linters:

* Don't use variable or parameter names that shadow builtin functions and
types. For example, don't name a variable "file". (Unfortunately, Python uses
types. For example, don't name a variable "id". (Unfortunately, Python uses
many useful names for its builtin types and functions.)
* Sort imports alphabetically within their grouping to reduce duplicate
imports.

#### Exceptions

Expand All @@ -274,11 +271,6 @@ a few PEP8 rules in order to match existing code. In particular:
it's okay to make your new function and its parameters camelCase to match.
Try to use snake_case internally, however.

You should try to write Python 2 / Python 3 compatible code where possible.
Using `from __future__ import print_function, division, absolute_import` will
help with this. Some libraries run in Python 2 and Python 3 already; this
behaviour should be maintained.

### Documentation

New classes and functions should generally be documented using
Expand All @@ -293,17 +285,14 @@ be found on the Sphinx website.
### Tests

New code should also have unit tests. Tests are written in [unittest] style
and run with [py.test]. For tests requiring the Django ORM, we use the
Django-provided[TestCase], which extends `unittest.TestCase`.
and run with [pytest]. For tests requiring the Django ORM, we use
[pytest-django].

Tests are found in the `tests` directory, a sibling of the directory containing
the code. `test_foo.py` contains tests for `foo.py`. For clarity, group tests
for the same function and similar tests into the same class within that file.
This will also allow you to share setup and teardown code.

If you are testing code that makes HTTP requests, using [VCR.py] is highly
recommended. It should already be a development dependency.

### Commit History

A clean commit history makes it easier to see what changes are related, and why
Expand Down Expand Up @@ -407,36 +396,33 @@ Further content comes after a blank line.
[documentation]: https://github.com/artefactual/archivematica-docs/
[mailing list]: https://groups.google.com/forum/#!forum/archivematica
[Archivematica Issues repo]: https://github.com/archivematica/Issues
[user]: https://groups.google.com/forum/#!forum/archivematica
[Archivematica Issues repo]: https://github.com/archivematica/Issues
[Issues repo wiki]: https://github.com/archivematica/Issues/wiki
[files]: https://help.github.com/articles/getting-permanent-links-to-files/
[code snippets]: https://help.github.com/articles/creating-a-permanent-link-to-a-code-snippet/
[development installation]: https://wiki.archivematica.org/Getting_started#Installation
[development installation]: https://github.com/artefactual/archivematica/tree/qa/1.x/hack#archivematica-development-on-docker-compose
[GitHub]: https://github.com/
[guide]: https://help.github.com/articles/fork-a-repo
[excellent]: https://help.github.com/articles/using-pull-requests
[Line comment]: http://i.imgur.com/FsWppGN.png
[Line comment]: https://i.imgur.com/FsWppGN.png
[code review guidelines]: code_review.md
[interactive rebase feature]: http://www.git-scm.com/book/en/Git-Tools-Rewriting-History
[interactive rebase feature]: https://www.git-scm.com/book/en/Git-Tools-Rewriting-History
[Contributor's Agreement]: https://wiki.archivematica.org/images/e/e6/Archivematica-CLA-firstname-lastname-YYYY.pdf
[Apache Foundation]: http://apache.org
[contributor license]: http://www.apache.org/licenses/icla.txt
[Artefactual Systems]: http://artefactual.com
[Apache Foundation]: https://apache.org
[contributor license]: https://www.apache.org/licenses/icla.txt
[Artefactual Systems]: https://artefactual.com
[PEP8]: https://www.python.org/dev/peps/pep-0008/
[Black]: https://github.com/ambv/black
[flake8]: https://pypi.python.org/pypi/flake8
[continuous integration system]: https://travis-ci.org/artefactual/archivematica
[Pylint]: https://www.pylint.org/
[continuous integration system]: https://github.com/artefactual/archivematica/actions
[pre-commit]: https://pre-commit.com/
[docstrings]: https://en.wikipedia.org/wiki/Docstring#Python
[PEP 257]: https://www.python.org/dev/peps/pep-0257/
[Sphinx-compatible docstrings]: http://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions
[examples]: http://sphinx-doc.org/domains.html#info-field-lists
[attributes to use]: http://sphinx-doc.org/domains.html#the-python-domain
[unittest]: https://docs.python.org/2/library/unittest.html
[py.test]: http://pytest.org
[TestCase]: https://docs.djangoproject.com/en/1.8/topics/testing/tools/#django.test.TestCase
[VCR.py]: https://github.com/kevin1024/vcrpy
[Sphinx-compatible docstrings]: https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions
[examples]: https://www.sphinx-doc.org/en/master/#info-field-lists
[attributes to use]: https://www.sphinx-doc.org/en/master/#the-python-domain
[unittest]: https://docs.python.org/3.9/library/unittest.html
[pytest]: https://docs.pytest.org/
[pytest-django]: https://pytest-django.readthedocs.io/en/latest/database.html
[How to Write a Git Commit Message]: https://chris.beams.io/posts/git-commit/
[seven rules of a great Git commit message]: https://chris.beams.io/posts/git-commit/#seven-rules
[imperative mood]: https://chris.beams.io/posts/git-commit/#imperative